CREATE FUNCTION (Transact-SQL)CREATE FUNCTION (Transact-SQL)

ESTE TÓPICO APLICA-SE A:simSQL Server (a partir de 2008)simBanco de Dados SQL do Microsoft AzurenãoAzure SQL Data Warehouse nãoParallel Data Warehouse THIS TOPIC APPLIES TO:yesSQL Server (starting with 2008)yesAzure SQL DatabasenoAzure SQL Data Warehouse noParallel Data Warehouse

Cria uma função definida pelo usuário no SQL ServerSQL Server e no Banco de dados SQL do AzureAzure SQL Database.Creates a user-defined function in SQL ServerSQL Server and Banco de dados SQL do AzureAzure SQL Database. Uma função definida pelo usuário é uma rotina Transact-SQLTransact-SQL ou CLR (Common Language Runtime) que aceita parâmetros, executa uma ação, como um cálculo complexo, e retorna o resultado dessa ação como um valor.A user-defined function is a Transact-SQLTransact-SQL or common language runtime (CLR) routine that accepts parameters, performs an action, such as a complex calculation, and returns the result of that action as a value. O valor de retorno pode ser um valor escalar (único) ou uma tabela.The return value can either be a scalar (single) value or a table. Use essa instrução para criar uma rotina reutilizável que possa ser usada destas maneiras:Use this statement to create a reusable routine that can be used in these ways:

  • Em instruções Transact-SQLTransact-SQL, como SELECTIn Transact-SQLTransact-SQL statements such as SELECT

  • Em aplicativos que chamam a funçãoIn applications calling the function

  • Na definição de outra função definida pelo usuárioIn the definition of another user-defined function

  • Para parametrizar uma exibição ou aprimorar a funcionalidade de uma exibição indexadaTo parameterize a view or improve the functionality of an indexed view

  • Para definir uma coluna em uma tabelaTo define a column in a table

  • Para definir uma restrição CHECK em uma colunaTo define a CHECK constraint on a column

  • Para substituir um procedimento armazenadoTo replace a stored procedure

  • Usar uma função embutida como um predicado de filtro para uma política de segurançaUse an inline function as a filter predicate for a security policy

Observação

A integração do CLR do .NET Framework para SQL Server é discutida neste tópico.The integration of .NET Framework CLR into SQL Server is discussed in this topic. Integração CLR não se aplica ao banco de dados do SQL Azure.CLR integration does not apply to Azure SQL Database.

Ícone de link do tópico Convenções da sintaxe Transact-SQLTopic link icon Transact-SQL Syntax Conventions

SintaxeSyntax

-- Transact-SQL Scalar Function Syntax  
CREATE [ OR ALTER ] FUNCTION [ schema_name. ] function_name   
( [ { @parameter_name [ AS ][ type_schema_name. ] parameter_data_type   
    [ = default ] [ READONLY ] }   
    [ ,...n ]  
  ]  
)  
RETURNS return_data_type  
    [ WITH <function_option> [ ,...n ] ]  
    [ AS ]  
    BEGIN   
        function_body   
        RETURN scalar_expression  
    END  
[ ; ]  
-- Transact-SQL Inline Table-Valued Function Syntax   
CREATE [ OR ALTER ] FUNCTION [ schema_name. ] function_name   
( [ { @parameter_name [ AS ] [ type_schema_name. ] parameter_data_type   
    [ = default ] [ READONLY ] }   
    [ ,...n ]  
  ]  
)  
RETURNS TABLE  
    [ WITH <function_option> [ ,...n ] ]  
    [ AS ]  
    RETURN [ ( ] select_stmt [ ) ]  
[ ; ]  
-- Transact-SQL Multi-Statement Table-Valued Function Syntax  
CREATE [ OR ALTER ] FUNCTION [ schema_name. ] function_name   
( [ { @parameter_name [ AS ] [ type_schema_name. ] parameter_data_type   
    [ = default ] [READONLY] }   
    [ ,...n ]  
  ]  
)  
RETURNS @return_variable TABLE <table_type_definition>  
    [ WITH <function_option> [ ,...n ] ]  
    [ AS ]  
    BEGIN   
        function_body   
        RETURN  
    END  
[ ; ]  
-- Transact-SQL Function Clauses   
<function_option>::=   
{  
    [ ENCRYPTION ]  
  | [ SCHEMABINDING ]  
  | [ RETURNS NULL ON NULL INPUT | CALLED ON NULL INPUT ]  
  | [ EXECUTE_AS_Clause ]  
}  

<table_type_definition>:: =   
( { <column_definition> <column_constraint>   
  | <computed_column_definition> }   
    [ <table_constraint> ] [ ,...n ]  
)   
<column_definition>::=  
{  
    { column_name data_type }  
    [ [ DEFAULT constant_expression ]   
      [ COLLATE collation_name ] | [ ROWGUIDCOL ]  
    ]  
    | [ IDENTITY [ (seed , increment ) ] ]  
    [ <column_constraint> [ ...n ] ]   
}  

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

<computed_column_definition>::=  
column_name AS computed_column_expression   

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

<index_option>::=  
{   
    PAD_INDEX = { ON | OFF }   
  | FILLFACTOR = fillfactor   
  | IGNORE_DUP_KEY = { ON | OFF }  
  | STATISTICS_NORECOMPUTE = { ON | OFF }   
  | ALLOW_ROW_LOCKS = { ON | OFF }  
  | ALLOW_PAGE_LOCKS ={ ON | OFF }   
}  
-- CLR Scalar Function Syntax  
CREATE [ OR ALTER ] FUNCTION [ schema_name. ] function_name   
( { @parameter_name [AS] [ type_schema_name. ] parameter_data_type   
    [ = default ] }   
    [ ,...n ]  
)  
RETURNS { return_data_type }  
    [ WITH <clr_function_option> [ ,...n ] ]  
    [ AS ] EXTERNAL NAME <method_specifier>  
[ ; ]  
-- CLR Table-Valued Function Syntax  
CREATE [ OR ALTER ] FUNCTION [ schema_name. ] function_name   
( { @parameter_name [AS] [ type_schema_name. ] parameter_data_type   
    [ = default ] }   
    [ ,...n ]  
)  
RETURNS TABLE <clr_table_type_definition>   
    [ WITH <clr_function_option> [ ,...n ] ]  
    [ ORDER ( <order_clause> ) ]  
    [ AS ] EXTERNAL NAME <method_specifier>  
[ ; ]  
-- CLR Function Clauses  
<order_clause> ::=   
{  
   <column_name_in_clr_table_type_definition>  
   [ ASC | DESC ]   
} [ ,...n]   

<method_specifier>::=  
    assembly_name.class_name.method_name  

<clr_function_option>::=  
}  
    [ RETURNS NULL ON NULL INPUT | CALLED ON NULL INPUT ]  
  | [ EXECUTE_AS_Clause ]  
}  

<clr_table_type_definition>::=   
( { column_name data_type } [ ,...n ] )  
-- In-Memory OLTP: Syntax for natively compiled, scalar user-defined function  
CREATE [ OR ALTER ] FUNCTION [ schema_name. ] function_name   
 ( [ { @parameter_name [ AS ][ type_schema_name. ] parameter_data_type   
    [ NULL | NOT NULL ] [ = default ] [ READONLY ] }   
    [ ,...n ]   
  ]   
)   
RETURNS return_data_type  
     WITH <function_option> [ ,...n ]   
    [ AS ]   
    BEGIN ATOMIC WITH (set_option [ ,... n ])   
        function_body   
        RETURN scalar_expression  
    END  

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

ArgumentosArguments

OU ALTEROR ALTER
Aplica-se a: Azure Banco de Dados SQLSQL Database, SQL ServerSQL Server (começando com SQL Server 2016SQL Server 2016 SP1).Applies to: Azure Banco de Dados SQLSQL Database, SQL ServerSQL Server (starting with SQL Server 2016SQL Server 2016 SP1).

Altera condicionalmente a função somente se ele já existe.Conditionally alters the function only if it already exists.

Observação

Sintaxe [ou ALTER] opcional para o CLR está disponível desde SQL Server 2016SQL Server 2016 SP1 CU1.Optional [OR ALTER] syntax for CLR is available starting with SQL Server 2016SQL Server 2016 SP1 CU1.

schema_nameschema_name
É o nome do esquema ao qual a função definida pelo usuário pertence.Is the name of the schema to which the user-defined function belongs.

nome_da_funçãofunction_name
É o nome da função definida pelo usuário.Is the name of the user-defined function. Nomes de função devem estar de acordo com as regras de identificadores e deve ser exclusivo no banco de dados e seu esquema.Function names must comply with the rules for identifiers and must be unique within the database and to its schema.

Observação

São necessários parênteses depois do nome de função mesmo que um parâmetro não seja especificado.Parentheses are required after the function name even if a parameter is not specified.

@parameter_name@parameter_name
É um parâmetro na função definida pelo usuário.Is a parameter in the user-defined function. Podem ser declarados um ou mais parâmetros.One or more parameters can be declared.

Uma função pode ter no máximo 2.100 parâmetros.A function can have a maximum of 2,100 parameters. O valor de cada parâmetro declarado deve ser fornecido pelo usuário quando a função é executada, a menos que seja definido um padrão para o parâmetro.The value of each declared parameter must be supplied by the user when the function is executed, unless a default for the parameter is defined.

Especifique um nome de parâmetro usando um sinal de arroba (@) como o primeiro caractere.Specify a parameter name by using an at sign (@) as the first character. O nome do parâmetro deve estar em conformidade com as regras de identificadores.The parameter name must comply with the rules for identifiers. Os parâmetros são locais para a função. Os mesmos nomes de parâmetro podem ser usados em outras funções.Parameters are local to the function; the same parameter names can be used in other functions. Os parâmetros só podem assumir o lugar de constantes. Eles não podem ser usados no lugar de nomes de tabela, nomes de coluna ou nomes de outros objetos de banco de dados.Parameters can take the place only of constants; they cannot be used instead of table names, column names, or the names of other database objects.

Observação

ANSI_WARNINGS não é cumprido quando você passa parâmetros em um procedimento armazenado, em uma função definida pelo usuário ou quando declara ou define variáveis em uma instrução de lote.ANSI_WARNINGS is not honored when you pass parameters in a stored procedure, user-defined function, or when you declare and set variables in a batch statement. Por exemplo, se a variável é definida como caractere (3)e definido como um valor maior do que três caracteres, os dados são truncados para o tamanho definido e a inserção ou atualização instrução tem sucesso.For example, if a variable is defined as char(3), and then set to a value larger than three characters, the data is truncated to the defined size and the INSERT or UPDATE statement succeeds.

[ type_schema_name.[ type_schema_name. ] parameter_data_type] parameter_data_type
É o tipo de dados do parâmetro e, opcionalmente, o esquema ao qual ele pertence.Is the parameter data type, and optionally the schema to which it belongs. Para Transact-SQLTransact-SQL funções, todos os tipos de dados, incluindo tipos CLR definidos pelo usuário e tipos de tabela definidos pelo usuário, são permitidas, exceto o timestamp tipo de dados.For Transact-SQLTransact-SQL functions, all data types, including CLR user-defined types and user-defined table types, are allowed except the timestamp data type. Para funções CLR, todos os tipos de dados, incluindo tipos CLR definidos pelo usuário, são permitidos, exceto texto, ntext, imagemdefinida pelo usuário tipos de tabela e carimbo de hora tipos de dados.For CLR functions, all data types, including CLR user-defined types, are allowed except text, ntext, image, user-defined table types and timestamp data types. Os tipos não escalares, cursor e tabela, não pode ser especificado como um tipo de dados do parâmetro em Transact-SQLTransact-SQL ou funções CLR.The nonscalar types, cursor and table, cannot be specified as a parameter data type in either Transact-SQLTransact-SQL or CLR functions.

Se type_schema_name não for especificado, o Mecanismo de Banco de DadosDatabase Engine procura o scalar_parameter_data_type na seguinte ordem:If type_schema_name is not specified, the Mecanismo de Banco de DadosDatabase Engine looks for the scalar_parameter_data_type in the following order:

  • O esquema que contém os nomes dos tipos de dados do sistema SQL ServerSQL Server.The schema that contains the names of SQL ServerSQL Server system data types.

  • O esquema padrão do usuário atual no banco de dados atual.The default schema of the current user in the current database.

  • O esquema dbo no banco de dados atual.The dbo schema in the current database.

    [=padrão ][ =default ]
    É um valor padrão para o parâmetro.Is a default value for the parameter. Se um padrão valor for definido, a função pode ser executada sem especificar um valor para esse parâmetro.If a default value is defined, the function can be executed without specifying a value for that parameter.

Observação

Valores de parâmetro padrão podem ser especificados para funções CLR exceto para o varchar (max) e varbinary (max) tipos de dados.Default parameter values can be specified for CLR functions except for the varchar(max) and varbinary(max) data types.

Quando um parâmetro da função tiver um valor padrão, a palavra-chave DEFAULT deverá ser especificada quando a função for chamada para recuperar o valor padrão.When a parameter of the function has a default value, the keyword DEFAULT must be specified when the function is called to retrieve the default value. 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.This behavior is different from using parameters with default values in stored procedures in which omitting the parameter also implies the default value. Porém, a palavra-chave DEFAULT não é necessária ao invocar uma função escalar por meio da instrução EXECUTE.However, the DEFAULT keyword is not required when invoking a scalar function by using the EXECUTE statement.

READONLYREADONLY
Indica que o parâmetro não pode ser atualizado ou modificado na definição da função.Indicates that the parameter cannot be updated or modified within the definition of the function. Se o tipo de parâmetro for um tipo de tabela definido pelo usuário, READONLY deverá ser especificado.If the parameter type is a user-defined table type, READONLY should be specified.

return_data_typereturn_data_type
É o valor de retorno de uma função escalar definida pelo usuário.Is the return value of a scalar user-defined function. Para Transact-SQLTransact-SQL funções, todos os tipos de dados, incluindo tipos CLR definidos pelo usuário, são permitidas, exceto o timestamp tipo de dados.For Transact-SQLTransact-SQL functions, all data types, including CLR user-defined types, are allowed except the timestamp data type. Para funções CLR, todos os tipos de dados, incluindo tipos CLR definidos pelo usuário, são permitidos, exceto o texto, ntext, imagem, e timestamptipos de dados.For CLR functions, all data types, including CLR user-defined types, are allowed except the text, ntext, image, and timestamp data types. Os tipos não escalares, cursor e tabela, não pode ser especificado como um tipo de dados de retorno em Transact-SQLTransact-SQL ou funções CLR.The nonscalar types, cursor and table, cannot be specified as a return data type in either Transact-SQLTransact-SQL or CLR functions.

function_bodyfunction_body
Especifica que uma série de instruções Transact-SQLTransact-SQL, que juntas não produzem um efeito colateral, como a modificação de uma tabela, define o valor da função.Specifies that a series of Transact-SQLTransact-SQL statements, which together do not produce a side effect such as modifying a table, define the value of the function. function_body é usado somente em funções escalares e funções com valor de tabela de várias instruções.function_body is used only in scalar functions and multistatement table-valued functions.

Em funções escalares, function_body é uma série de Transact-SQLTransact-SQL instruções que juntas são avaliadas como um valor escalar.In scalar functions, function_body is a series of Transact-SQLTransact-SQL statements that together evaluate to a scalar value.

Em funções com valor de tabela com várias instruções, function_body é uma série de Transact-SQLTransact-SQL variável de retorno de instruções que preenchem uma tabela.In multistatement table-valued functions, function_body is a series of Transact-SQLTransact-SQL statements that populate a TABLE return variable.

scalar_expressionscalar_expression
Especifica o valor escalar que a função escalar retorna.Specifies the scalar value that the scalar function returns.

TABLETABLE
Especifica que o valor de retorno da função com valor de tabela é uma tabela.Specifies that the return value of the table-valued function is a table. Somente constantes e @local_variables podem ser passados para funções com valor de tabela.Only constants and @local_variables can be passed to table-valued functions.

Em funções com valor de tabela embutidas, o valor de retorno TABLE é definido por uma única instrução SELECT.In inline table-valued functions, the TABLE return value is defined through a single SELECT statement. As funções embutidas não têm variáveis de retorno associadas.Inline functions do not have associated return variables.

Em funções com valor de tabela com várias instruções, @return_variable é uma variável de tabela, usado para armazenar e acumular as linhas que devem ser retornadas como o valor da função.In multistatement table-valued functions, @return_variable is a TABLE variable, used to store and accumulate the rows that should be returned as the value of the function. @return_variable pode ser especificado somente para Transact-SQLTransact-SQL funções e não para funções CLR. @return_variable can be specified only for Transact-SQLTransact-SQL functions and not for CLR functions.

Aviso

Ingressando em uma tabela de várias instruções com valor de função em um FROM cláusula é possível, mas pode resultar em desempenho insatisfatório.Joining to a multistatement table valued function in a FROM clause is possible, but can give poor performance. O SQL ServerSQL Server não pode usar todas as técnicas otimizadas em algumas instruções a serem incluídas em uma função multistatement, resultando em um plano de consulta de qualidade inferior. SQL ServerSQL Server is unable to use all the optimized techniques against some statements that can be included in a multistatement function, resulting in a suboptimal query plan. Para obter o melhor desempenho possível, sempre que possível use junções entre tabelas base em vez de funções.To obtain the best possible performance, whenever possible use joins between base tables instead of functions.

select_stmtselect_stmt
É a única instrução SELECT que define o valor de retorno de uma função com valor de tabela embutida.Is the single SELECT statement that defines the return value of an inline table-valued function.

ORDEM (<order_clause >) Especifica a ordem na qual os resultados estão sendo retornados da função com valor de tabela.ORDER (<order_clause>) Specifies the order in which results are being returned from the table-valued function. Para obter mais informações, consulte a seção "Orientação sobre como usar a ordem de classificação" mais adiante neste tópico.For more information, see the section, "Guidance on Using Sort Order," later in this topic.

NOME externo <method_specifier > nome_do_assembly. class_name. nome_do_método aplica-se a: SQL Server 2008SQL Server 2008 por meio de SQL Server 2017SQL Server 2017.EXTERNAL NAME <method_specifier> assembly_name.class_name.method_name Applies to: SQL Server 2008SQL Server 2008 through SQL Server 2017SQL Server 2017.

Especifica o assembly e o método ao qual o nome da função criado deve referir-se.Specifies the assembly and method to which the created function name shall refer.

  • nome_do_assembly -deve corresponder a um valor na name colunaassembly_name - must match a value in the name column of
    SELECT * FROM sys.assemblies;.SELECT * FROM sys.assemblies;.
    Esse é o nome usado na instrução CREATE ASSEMBLY.This is the name that was used on the CREATE ASSEMBLY statement.

  • class_name -deve corresponder a um valor na assembly_name colunaclass_name - must match a value in the assembly_name column of
    SELECT * FROM sys.assembly_modules;.SELECT * FROM sys.assembly_modules;.
    Muitas vezes o valor contém um ponto incorporado ou ponto.Often the value contains an embedded period or dot. Nesses casos o Transact-SQL sintaxe requer que o valor seja vinculado a um par de [colchetes], ou com um par de aspas duplas "".In such cases the Transact-SQL syntax requires that the value be bounded with a pair of straight brackets [], or with a pair of double quotation marks "".

  • nome_do_método -deve corresponder a um valor na method_name colunamethod_name - must match a value in the method_name column of
    SELECT * FROM sys.assembly_modules;.SELECT * FROM sys.assembly_modules;.
    O método deve ser estático.The method must be static.

    Um exemplo típico, para MyFood.DLL, onde todos os tipos estão no namespace MyFood, o valor EXTERNAL NAME poderia ser:In a typical example, for MyFood.DLL, in which all types are in the MyFood namespace, the EXTERNAL NAME value could be:
    MyFood.[MyFood.MyClass].MyStaticMethod

Observação

Por padrão, o SQL ServerSQL Server não pode executar código CLR.By default, SQL ServerSQL Server cannot execute CLR code. Você pode criar, modificar e descartar objetos do banco de dados que fazem referência a módulos CLR; No entanto, você não pode executar essas referências no SQL ServerSQL Server até que você habilite o opção clr enabled.You can create, modify, and drop database objects that reference common language runtime modules; however, you cannot execute these references in SQL ServerSQL Server until you enable the clr enabled option. Para habilitar essa opção, use sp_configure.To enable this option, use sp_configure.

Observação

Essa opção não está disponível em um banco de dados independente.This option is not available in a contained database.

<table_type_definition > ({ <column_definition > <column_constraint > | <computed_column_definition >} [ <table_constraint >] [,... n ]) Define o tipo de dados da tabela para uma Transact-SQLTransact-SQL função.<table_type_definition> ( { <column_definition> <column_constraint> | <computed_column_definition> } [ <table_constraint> ] [ ,...n ] ) Defines the table data type for a Transact-SQLTransact-SQL function. A declaração da tabela inclui definições de coluna e restrições de coluna ou tabela.The table declaration includes column definitions and column or table constraints. A tabela sempre é colocada no grupo de arquivos primário.The table is always put in the primary filegroup.

<clr_table_type_definition > ({ column_namedata_type } [,... n ]) Aplica-se a: SQL Server 2008SQL Server 2008 por meio de SQL Server 2017SQL Server 2017, Banco de Dados SQLSQL Database (visualização em algumas regiões). |< clr_table_type_definition > ( { column_namedata_type } [ ,...n ] ) Applies to: SQL Server 2008SQL Server 2008 through SQL Server 2017SQL Server 2017, Banco de Dados SQLSQL Database (Preview in some regions).|

Define os tipos de dados de tabela para uma função CLR.Defines the table data types for a CLR function. A declaração de tabela inclui somente nomes de colunas e tipos de dados.The table declaration includes only column names and data types. A tabela sempre é colocada no grupo de arquivos primário.The table is always put in the primary filegroup.

NULO | NÃO NULONULL|NOT NULL
Suporte apenas para funções escalares definidas pelo usuário.Supported only for natively compiled, scalar user-defined functions. Para obter mais informações, consulte funções escalares definidas pelo usuário para OLTP na memória.For more information, see Scalar User-Defined Functions for In-Memory OLTP.

NATIVE_COMPILATIONNATIVE_COMPILATION
Indica se uma função definida pelo usuário é compilada nativamente.Indicates whether a user-defined function is natively compiled. Esse argumento é exigido para as funções escalares definidas pelo usuário.This argument is required for natively compiled, scalar user-defined functions.

BEGIN ATOMIC COMBEGIN ATOMIC WITH
Suporte para somente compilados nativamente, escalar definida pelo usuário, funções e é necessário.Supported only for natively compiled, scalar user-defined functions, and is required. Para obter mais informações, veja Blocos atômicos.For more information, see Atomic Blocks.

SCHEMABINDINGSCHEMABINDING
O argumento SCHEMABINDING é exigido para as funções escalares definidas pelo usuário.The SCHEMABINDING argument is required for natively compiled, scalar user-defined functions.

EXECUTE ASEXECUTE AS
EXECUTE AS é exigida para as funções escalares definidas pelo usuário.EXECUTE AS is required for natively compiled, scalar user-defined functions.

<function_option >:: = e <clr_function_option >:: =<function_option>::= and <clr_function_option>::=

Especifica que a função terá uma ou mais das opções a seguir.Specifies that the function will have one or more of the following options.

ENCRYPTIONENCRYPTION
Aplica-se a: do SQL Server 2008SQL Server 2008 ao SQL Server 2017SQL Server 2017.Applies to: SQL Server 2008SQL Server 2008 through SQL Server 2017SQL Server 2017.

Indica que o Mecanismo de Banco de DadosDatabase Engine converterá o texto original da instrução CREATE FUNCTION em um formato ofuscado.Indicates that the Mecanismo de Banco de DadosDatabase Engine will convert the original text of the CREATE FUNCTION statement to an obfuscated format. A saída do ofuscamento não é diretamente visível em nenhuma exibição do catálogo.The output of the obfuscation is not directly visible in any catalog views. Os usuários que não tiverem nenhum acesso a tabelas do sistema ou arquivos de banco de dados não poderão recuperar o texto ofuscado.Users that have no access to system tables or database files cannot retrieve the obfuscated text. No entanto, o texto estará disponível para usuários privilegiados que puderem acessar as tabelas do sistema sobre a porta DAC ou acessar diretamente os arquivos de banco de dados.However, the text will be available to privileged users that can either access system tables over the DAC port or directly access database files. Além disso, os usuários que podem anexar um depurador ao processo de servidor também podem recuperar o procedimento original da memória em tempo de execução.Also, users that can attach a debugger to the server process can retrieve the original procedure from memory at runtime. Para obter mais informações sobre como acessar metadados do sistema, consulte configuração de visibilidade de metadados.For more information about accessing system metadata, see Metadata Visibility Configuration.

O uso dessa opção impede que a função seja publicada como parte da replicação do SQL ServerSQL Server.Using this option prevents the function from being published as part of SQL ServerSQL Server replication. Essa opção não pode ser especificada para funções CLR.This option cannot be specified for CLR functions.

SCHEMABINDINGSCHEMABINDING
Especifica que a função está associada aos objetos de banco de dados referenciados por ela.Specifies that the function is bound to the database objects that it references. Quando SCHEMABINDING for especificado, os objetos base não poderão ser modificadas de um modo que possa afetar a definição da função.When SCHEMABINDING is specified, the base objects cannot be modified in a way that would affect the function definition. A própria definição da função deve ser primeiro modificada ou descartada para remover as dependências no objeto a ser modificado.The function definition itself must first be modified or dropped to remove dependencies on the object that is to be modified.

A associação da função aos objetos referenciados por ela será removida somente quando ocorrer uma das ações a seguir:The binding of the function to the objects it references is removed only when one of the following actions occurs:

  • A função for descartada.The function is dropped.

  • A função for modificada com o uso da instrução ALTER sem a especificação da opção SCHEMABINDING.The function is modified by using the ALTER statement with the SCHEMABINDING option not specified.

    Uma função poderá ser associada a esquemas apenas se as condições a seguir forem verdadeiras:A function can be schema bound only if the following conditions are true:

  • A função é uma função Transact-SQLTransact-SQL.The function is a Transact-SQLTransact-SQL function.

  • As exibições e funções definidas pelo usuário referenciadas pela função também são associadas a esquema.The user-defined functions and views referenced by the function are also schema-bound.

  • Os objetos referenciados pela função são referenciados com um nome de duas partes.The objects referenced by the function are referenced using a two-part name.

  • A função e os objetos aos quais ela faz referência pertencem ao mesmo banco de dados.The function and the objects it references belong to the same database.

  • O usuário que executou a instrução CREATE FUNCTION tem permissão REFERENCES nos objetos do banco de dados referidos pela função.The user who executed the CREATE FUNCTION statement has REFERENCES permission on the database objects that the function references.

    RETORNA NULL EM ENTRADA NULL | CHAMADO EM ENTRADA NULLRETURNS NULL ON NULL INPUT | CALLED ON NULL INPUT
    Especifica o OnNULLCall atributo de uma função com valor escalar.Specifies the OnNULLCall attribute of a scalar-valued function. Se não for especificado, CALLED ON NULL INPUT será implícito por padrão.If not specified, CALLED ON NULL INPUT is implied by default. Isso significa que o corpo da função será executado mesmo que NULL seja passado como um argumento.This means that the function body executes even if NULL is passed as an argument.

    Se RETURNS NULL ON NULL INPUT estiver especificado em uma função CLR, isso indicará que o SQL ServerSQL Server poderá retornar NULL quando qualquer um dos argumentos recebidos for NULL, sem realmente invocar o corpo da função.If RETURNS NULL ON NULL INPUT is specified in a CLR function, it indicates that SQL ServerSQL Server can return NULL when any of the arguments it receives is NULL, without actually invoking the body of the function. Se o método de uma função CLR especificado no <method_specifier > já tem um atributo personalizado que indique RETURNS NULL ON NULL INPUT, mas a instrução CREATE FUNCTION indica CALLED ON NULL INPUT, o usa da instrução CREATE FUNCTION precedência.If the method of a CLR function specified in <method_specifier> already has a custom attribute that indicates RETURNS NULL ON NULL INPUT, but the CREATE FUNCTION statement indicates CALLED ON NULL INPUT, the CREATE FUNCTION statement takes precedence. O OnNULLCall atributo não pode ser especificado para funções CLR com valor de tabela.The OnNULLCall attribute cannot be specified for CLR table-valued functions.

    Cláusula EXECUTE ASEXECUTE AS Clause
    Especifica o contexto de segurança sob o qual a função definida pelo usuário é executada.Specifies the security context under which the user-defined function is executed. Portanto, é possível controlar a conta de usuário usada pelo SQL ServerSQL Server para validar permissões em quaisquer objetos do banco de dados referidos pela função.Therefore, you can control which user account SQL ServerSQL Server uses to validate permissions on any database objects that are referenced by the function.

Observação

EXECUTE AS não pode ser especificada para funções definidas pelo usuário embutidas.EXECUTE AS cannot be specified for inline user-defined functions.

Para obter mais informações, veja Cláusula EXECUTE AS (Transact-SQL).For more information, see EXECUTE AS Clause (Transact-SQL).

<column_definition >:: =< column_definition >::=

Define o tipo de dados da tabela.Defines the table data type. A declaração da tabela inclui definições de coluna e restrições.The table declaration includes column definitions and constraints. Para funções CLR, apenas column_name e data_type pode ser especificado.For CLR functions, only column_name and data_type can be specified.

column_namecolumn_name
É o nome de uma coluna da tabela.Is the name of a column in the table. Os nomes de coluna devem estar em conformidade com as regras de identificadores e devem ser exclusivos na tabela.Column names must comply with the rules for identifiers and must be unique in the table. nome da coluna pode consistir de 1 a 128 caracteres.column_name can consist of 1 through 128 characters.

data_typedata_type
Especifica o tipo de dados da coluna.Specifies the column data type. Para Transact-SQLTransact-SQL funções, todos os tipos de dados, incluindo tipos CLR definidos pelo usuário, são permitidas, exceto timestamp.For Transact-SQLTransact-SQL functions, all data types, including CLR user-defined types, are allowed except timestamp. Para funções CLR, todos os tipos de dados, incluindo tipos CLR definidos pelo usuário, são permitidos, exceto texto, ntext, imagem, char, varchar, varchar (max), e timestamp. O tipo não escalar cursor não pode ser especificado como um tipo de dados de coluna em Transact-SQLTransact-SQL ou funções CLR.For CLR functions, all data types, including CLR user-defined types, are allowed except text, ntext, image, char, varchar, varchar(max), and timestamp.The nonscalar type cursor cannot be specified as a column data type in either Transact-SQLTransact-SQL or CLR functions.

PADRÃO constant_expressionDEFAULT constant_expression
Especifica o valor fornecido para a coluna quando um valor não for fornecido explicitamente durante uma inserção.Specifies the value provided for the column when a value is not explicitly supplied during an insert. constant_expression é uma constante, NULL ou um valor de função do sistema.constant_expression is a constant, NULL, or a system function value. Podem ser aplicadas definições DEFAULT a qualquer coluna, com exceção das que têm a propriedade IDENTITY.DEFAULT definitions can be applied to any column except those that have the IDENTITY property. DEFAULT não pode ser especificado para funções CLR com valor de tabela.DEFAULT cannot be specified for CLR table-valued functions.

COLLATE collation_nameCOLLATE collation_name
Especifica o agrupamento da coluna.Specifies the collation for the column. Se não for especificado, a coluna será atribuída ao agrupamento padrão do banco de dados.If not specified, the column is assigned the default collation of the database. O nome do agrupamento pode ser um nome de agrupamento do Windows ou um nome de agrupamento SQL.Collation name can be either a Windows collation name or a SQL collation name. Para obter uma lista de e para obter mais informações sobre agrupamentos, consulte nome de agrupamento do Windows ( Transact-SQL ) e SQL nome de agrupamento do servidor ( Transact-SQL ) .For a list of and more information about collations, see Windows Collation Name (Transact-SQL) and SQL Server Collation Name (Transact-SQL).

A cláusula COLLATE pode ser usada para alterar os agrupamentos somente de colunas do char, varchar, nchar, e nvarchar tipos de dados.The COLLATE clause can be used to change the collations only of columns of the char, varchar, nchar, and nvarchar data types.

COLLATE não pode ser especificado para funções CLR com valor de tabela.COLLATE cannot be specified for CLR table-valued functions.

ROWGUIDCOLROWGUIDCOL
Indica que a nova coluna é uma de coluna de identificador globalmente exclusivo de linha.Indicates that the new column is a row globally unique identifier column. Apenas uma uniqueidentifier coluna por tabela pode ser designada como a coluna ROWGUIDCOL.Only one uniqueidentifier column per table can be designated as the ROWGUIDCOL column. A propriedade ROWGUIDCOL pode ser atribuída somente a um uniqueidentifier coluna.The ROWGUIDCOL property can be assigned only to a uniqueidentifier column.

A propriedade ROWGUIDCOL não impõe exclusividade dos valores armazenados na coluna.The ROWGUIDCOL property does not enforce uniqueness of the values stored in the column. Também não gera automaticamente valores para novas linhas inseridas na tabela.It also does not automatically generate values for new rows inserted into the table. Para gerar valores exclusivos para cada coluna, use a função NEWID em instruções INSERT.To generate unique values for each column, use the NEWID function on INSERT statements. Um valor padrão pode ser especificado; entretanto, NEWID não pode ser especificado como o padrão.A default value can be specified; however, NEWID cannot be specified as the default.

IDENTITYIDENTITY
Indica que a nova coluna é uma coluna de identidade.Indicates that the new column is an identity column. Quando uma nova linha é adicionada à tabela, o SQL ServerSQL Server fornece um valor incremental exclusivo para a coluna.When a new row is added to the table, SQL ServerSQL Server provides a unique, incremental value for the column. Geralmente, as colunas de identidade são usadas juntamente com restrições PRIMARY KEY para servir como o identificador exclusivo de linha da tabela.Identity columns are typically used together with PRIMARY KEY constraints to serve as the unique row identifier for the table. A propriedade de identidade pode ser atribuída a tinyint, smallint, int, bigint, decimal(p,0), ou numeric(p,0) colunas.The IDENTITY property can be assigned to tinyint, smallint, int, bigint, decimal(p,0), or numeric(p,0) columns. Apenas uma coluna de identidade pode ser criada por tabela.Only one identity column can be created per table. Padrões associados e restrições DEFAULT não podem ser usados com uma coluna de identidade.Bound defaults and DEFAULT constraints cannot be used with an identity column. Você deve especificar ambos os semente e incremento ou nenhum deles.You must specify both the seed and increment or neither. Se nenhum for especificado, o padrão será (1,1).If neither is specified, the default is (1,1).

IDENTITY não pode ser especificado para funções CLR com valor de tabela.IDENTITY cannot be specified for CLR table-valued functions.

sementeseed
É o valor inteiro que será atribuído à primeira linha da tabela.Is the integer value to be assigned to the first row in the table.

incrementoincrement
É o valor inteiro para adicionar ao semente valor para linhas sucessivas na tabela.Is the integer value to add to the seed value for successive rows in the table.

<column_constraint >:: = e < table_constraint >:: =< column_constraint >::= and < table_constraint>::=

Define a restrição para uma coluna ou tabela especificada.Defines the constraint for a specified column or table. Para funções CLR, o único tipo de restrição permitido é NULL.For CLR functions, the only constraint type allowed is NULL. Não são permitidas restrições nomeadas.Named constraints are not allowed.

NULL | NOT NULLNULL | NOT NULL
Determina se são permitidos valores nulos na coluna.Determines whether null values are allowed in the column. NULL não é estritamente uma restrição, mas pode ser especificado simplesmente como NOT NULL.NULL is not strictly a constraint but can be specified just like NOT NULL. NOT NULL não pode ser especificado para funções CLR com valor de tabela.NOT NULL cannot be specified for CLR table-valued functions.

PRIMARY KEYPRIMARY KEY
É uma restrição que impõe integridade de entidade para uma coluna especificada por meio de um índice exclusivo.Is a constraint that enforces entity integrity for a specified column through a unique index. Em funções definidas pelo usuário com valor de tabela, a restrição PRIMARY KEY pode ser criada somente em uma coluna por tabela.In table-valued user-defined functions, the PRIMARY KEY constraint can be created on only one column per table. PRIMARY KEY não pode ser especificado para funções CLR com valor de tabela.PRIMARY KEY cannot be specified for CLR table-valued functions.

UNIQUEUNIQUE
É uma restrição que fornece integridade de entidade para uma coluna ou colunas especificadas por meio de um índice exclusivo.Is a constraint that provides entity integrity for a specified column or columns through a unique index. Uma tabela pode ter várias restrições UNIQUE.A table can have multiple UNIQUE constraints. UNIQUE não pode ser especificado para funções CLR com valor de tabela.UNIQUE cannot be specified for CLR table-valued functions.

CLUSTERED | NONCLUSTEREDCLUSTERED | NONCLUSTERED
Indica que um índice clusterizado ou não clusterizado será criado para a restrição PRIMARY KEY ou UNIQUE.Indicate that a clustered or a nonclustered index is created for the PRIMARY KEY or UNIQUE constraint. As restrições PRIMARY KEY usam CLUSTERED e as restrições UNIQUE usam NONCLUSTERED.PRIMARY KEY constraints use CLUSTERED, and UNIQUE constraints use NONCLUSTERED.

CLUSTERED só pode ser especificado para uma restrição.CLUSTERED can be specified for only one constraint. Se CLUSTERED for especificado para uma restrição UNIQUE e uma restrição PRIMARY KEY também for especificada, PRIMARY KEY usará NONCLUSTERED.If CLUSTERED is specified for a UNIQUE constraint and a PRIMARY KEY constraint is also specified, the PRIMARY KEY uses NONCLUSTERED.

CLUSTERED e NONCLUSTERED não podem ser especificados para funções CLR com valor de tabela.CLUSTERED and NONCLUSTERED cannot be specified for CLR table-valued functions.

CHECKCHECK
É uma restrição que impõe a integridade de domínio limitando os possíveis valores que podem ser inseridos em uma ou mais colunas.Is a constraint that enforces domain integrity by limiting the possible values that can be entered into a column or columns. Não podem ser especificadas restrições CHECK para funções CLR com valor de tabela.CHECK constraints cannot be specified for CLR table-valued functions.

Logical_Expressionlogical_expression
É uma expressão lógica que retorna TRUE ou FALSE.Is a logical expression that returns TRUE or FALSE.

<computed_column_definition >:: =<computed_column_definition>::=

Especifica uma coluna computada.Specifies a computed column. Para obter mais informações sobre colunas computadas, consulte CREATE TABLE ( Transact-SQL ) .For more information about computed columns, see CREATE TABLE (Transact-SQL).

column_namecolumn_name
É o nome da coluna computada.Is the name of the computed column.

computed_column_expressioncomputed_column_expression
É uma expressão que define o valor de uma coluna computada.Is an expression that defines the value of a computed column.

<index_option >:: =<index_option>::=

Especifica as opções de índice para o índice PRIMARY KEY ou UNIQUE.Specifies the index options for the PRIMARY KEY or UNIQUE index. Para obter mais informações sobre opções de índice, consulte CREATE INDEX ( Transact-SQL ) .For more information about index options, see CREATE INDEX (Transact-SQL).

PAD_INDEX = {ON | OFF }PAD_INDEX = { ON | OFF }
Especifica o preenchimento do índice.Specifies index padding. O padrão é OFF.The default is OFF.

FILLFACTOR = fator de preenchimentoFILLFACTOR = fillfactor
Especifica uma porcentagem que indica quanto o Mecanismo de Banco de DadosDatabase Engine deve preencher o nível folha de cada página de índice durante a criação ou alteração do índice.Specifies a percentage that indicates how full the Mecanismo de Banco de DadosDatabase Engine should make the leaf level of each index page during index creation or change. fator de preenchimento deve ser um valor inteiro de 1 a 100.fillfactor must be an integer value from 1 to 100. O padrão é 0.The default is 0.

IGNORE_DUP_KEY = {ON | OFF }IGNORE_DUP_KEY = { ON | OFF }
Especifica a resposta de erro quando uma operação de inserção tenta inserir valores da chave duplicada em um índice exclusivo.Specifies the error response when an insert operation attempts to insert duplicate key values into a unique index. A opção IGNORE_DUP_KEY aplica-se apenas a operações de inserção depois que o índice é criado ou recriado.The IGNORE_DUP_KEY option applies only to insert operations after the index is created or rebuilt. O padrão é OFF.The default is OFF.

STATISTICS_NORECOMPUTE = {ON | OFF }STATISTICS_NORECOMPUTE = { ON | OFF }
Especifica se as estatísticas de distribuição são recomputadas.Specifies whether distribution statistics are recomputed. O padrão é OFF.The default is OFF.

ALLOW_ROW_LOCKS = { ON | OFF}ALLOW_ROW_LOCKS = { ON | OFF }
Especifica se bloqueios de linha são permitidos.Specifies whether row locks are allowed. O padrão é ON.The default is ON.

ALLOW_PAGE_LOCKS = { ON | OFF}ALLOW_PAGE_LOCKS = { ON | OFF }
Especifica se bloqueios de página são permitidos.Specifies whether page locks are allowed. O padrão é ON.The default is ON.

Práticas recomendadasBest Practices

Se uma função definida pelo usuário não for criada com a cláusula SCHEMABINDING, as alterações feitas nos objetos subjacentes poderão afetar a definição da função e produzir resultados inesperados quando ela for chamada.If a user-defined function is not created with the SCHEMABINDING clause, changes that are made to underlying objects can affect the definition of the function and produce unexpected results when it is invoked. É recomendável que você implemente um dos seguintes métodos para garantir que a função não se torne desatualizada devido a alterações em seus objetos subjacentes:We recommend that you implement one of the following methods to ensure that the function does not become outdated because of changes to its underlying objects:

  • Especifique a cláusula WITH SCHEMABINDING quando estiver criando a função.Specify the WITH SCHEMABINDING clause when you are creating the function. Isso garante que os objetos referenciados na definição da função não possam ser modificados, a menos que a função também seja modificada.This ensures that the objects referenced in the function definition cannot be modified unless the function is also modified.

  • Execute o sp_refreshsqlmodule procedimento armazenado depois de modificar qualquer objeto que é especificado na definição da função.Execute the sp_refreshsqlmodule stored procedure after modifying any object that is specified in the definition of the function.

Tipos de dadosData Types

Se os parâmetros são especificados em uma função CLR, eles deverão ser SQL ServerSQL Server tipos conforme definido previamente para scalar_parameter_data_type.If parameters are specified in a CLR function, they should be SQL ServerSQL Server types as defined previously for scalar_parameter_data_type. Para obter informações sobre como comparar SQL ServerSQL Server tipos de dados do sistema para tipos de dados de integração CLR ou .NET Framework.NET Framework tipos de dados de tempo de execução de linguagem comum, consulte mapeamento de dados de parâmetro CLR.For information about comparing SQL ServerSQL Server system data types to CLR integration data types or .NET Framework.NET Framework common language runtime data types, see Mapping CLR Parameter Data.

Para SQL ServerSQL Server para referenciar o método correto quando está sobrecarregado em uma classe, o método indicado em <method_specifier > deve ter as seguintes características:For SQL ServerSQL Server to reference the correct method when it is overloaded in a class, the method indicated in <method_specifier> must have the following characteristics:

  • Receber o mesmo número de parâmetros como especificado em [,... n ].Receive the same number of parameters as specified in [ ,...n ].

  • Receber todos os parâmetros por valor, não por referência.Receive all the parameters by value, not by reference.

  • Use tipos de parâmetro que sejam compatíveis com os especificados na função SQL ServerSQL Server.Use parameter types that are compatible with those specified in the SQL ServerSQL Server function.

    Se o tipo de dados de retorno da função CLR Especifica um tipo de tabela (RETURNS TABLE), o tipo de dados de retorno do método no <method_specifier > deve ser do tipo IEnumerator ou IEnumerable, e presume-se que a interface é implementada pelo criador da função.If the return data type of the CLR function specifies a table type (RETURNS TABLE), the return data type of the method in <method_specifier> should be of type IEnumerator or IEnumerable, and it is assumed that the interface is implemented by the creator of the function. Ao contrário de Transact-SQLTransact-SQL funções, funções CLR não podem incluir restrições KEY, UNIQUE ou CHECK primária no <table_type_definition >.Unlike Transact-SQLTransact-SQL functions, CLR functions cannot include PRIMARY KEY, UNIQUE, or CHECK constraints in <table_type_definition>. Os tipos de dados de colunas especificado na <table_type_definition > devem corresponder aos tipos das colunas correspondentes do conjunto de resultados retornado pelo método na <method_specifier > em tempo de execução.The data types of columns specified in <table_type_definition> must match the types of the corresponding columns of the result set returned by the method in <method_specifier> at execution time. Essa verificação de tipo não é executada quando a função é criada.This type-checking is not performed at the time the function is created.

    Para obter mais informações sobre como programar funções CLR, consulte funções CLR definidas pelo usuário.For more information about how to program CLR functions, see CLR User-Defined Functions.

Comentários geraisGeneral Remarks

Funções com valor escalar podem ser invocadas quando expressões escalares são usadas.Scalar-valued functions can be invoked where scalar expressions are used. Isso inclui colunas computadas e definições de restrições CHECK.This includes computed columns and CHECK constraint definitions. Funções com valor escalar também podem ser executadas usando o EXECUTE instrução.Scalar-valued functions can also be executed by using the EXECUTE statement. Funções com valor escalar devem ser invocadas usando pelo menos o nome de duas partes da função.Scalar-valued functions must be invoked by using at least the two-part name of the function. Para obter mais informações sobre nomes de várias partes, consulte convenções de sintaxe do Transact-SQL ( Transact-SQL ) .For more information about multipart names, see Transact-SQL Syntax Conventions (Transact-SQL). Funções com valor de tabela podem ser invocadas quando expressões de tabela são permitidas na cláusula FROM de instruções SELECT, INSERT, UPDATE ou DELETE.Table-valued functions can be invoked where table expressions are allowed in the FROM clause of SELECT, INSERT, UPDATE, or DELETE statements. Para obter mais informações, consulte funções definidas pelo usuário executar.For more information, see Execute User-defined Functions.

InteroperabilidadeInteroperability

As instruções a seguir são válidas em uma função:The following statements are valid in a function:

  • Instruções de atribuição.Assignment statements.

  • Instruções de controle de fluxo com exceção das instruções TRY...CATCH.Control-of-Flow statements except TRY...CATCH statements.

  • Instruções DECLARE que definem variáveis de dados locais e cursores locais.DECLARE statements defining local data variables and local cursors.

  • Instruções SELECT que contêm listas de seleção com expressões que atribuem valores a variáveis locais.SELECT statements that contain select lists with expressions that assign values to local variables.

  • Operações de cursor que fazem referência a cursores locais que são declaradas, abertas, fechadas e desalocadas na função.Cursor operations referencing local cursors that are declared, opened, closed, and deallocated in the function. Apenas instruções FETCH que atribuem valores a variáveis locais usando a cláusula INTO são permitidas. Instruções FETCH que retornam dados ao cliente não são permitidas.Only FETCH statements that assign values to local variables using the INTO clause are allowed; FETCH statements that return data to the client are not allowed.

  • Instruções INSERT, UPDATE e DELETE que modificam variáveis de tabela locais.INSERT, UPDATE, and DELETE statements modifying local table variables.

  • Instruções EXECUTE que chamam procedimentos armazenados estendidos.EXECUTE statements calling extended stored procedures.

  • Para obter mais informações, consulte definida pelo usuário criar funções ( mecanismo de banco de dados ).For more information, see Create User-defined Functions (Database Engine).

Interoperabilidade de colunas computadasComputed Column Interoperability

As funções têm as seguintes propriedades.Functions have the following properties. Os valores dessas propriedades determinam se as funções podem ser usadas em colunas computadas que podem ser persistidas ou indexadas.The values of these properties determine whether functions can be used in computed columns that can be persisted or indexed.

PropriedadeProperty DescriptionDescription ObservaçõesNotes
IsDeterministicIsDeterministic A função é determinística ou não determinística.Function is deterministic or nondeterministic. O acesso a dados locais é permitido em funções determinísticas.Local data access is allowed in deterministic functions. Por exemplo, funções que sempre retornam o mesmo resultado quando são chamadas com o uso de um conjunto específico de valores de entrada e com o mesmo estado do banco de dados são rotuladas como determinísticas.For example, functions that always return the same result any time they are called by using a specific set of input values and with the same state of the database would be labeled deterministic.
IsPreciseIsPrecise A função é precisa ou imprecisa.Function is precise or imprecise. As funções imprecisas contêm operações, como operações de ponto flutuante.Imprecise functions contain operations such as floating point operations.
IsSystemVerifiedIsSystemVerified As propriedades de precisão e determinismo da função podem ser verificadas pelo SQL ServerSQL Server.The precision and determinism properties of the function can be verified by SQL ServerSQL Server.
SystemDataAccessSystemDataAccess A função acessa dados do sistema (catálogos ou tabelas virtuais do sistema) na instância local do SQL ServerSQL Server.Function accesses system data (system catalogs or virtual system tables) in the local instance of SQL ServerSQL Server.
UserDataAccessUserDataAccess A função acessa dados de usuário na instância local do SQL ServerSQL Server.Function accesses user data in the local instance of SQL ServerSQL Server. Inclui tabelas definidas pelo usuário e tabelas temporárias, mas não variáveis de tabela.Includes user-defined tables and temp tables, but not table variables.

As propriedades de precisão e determinismo de funções Transact-SQLTransact-SQL são automaticamente determinadas pelo SQL ServerSQL Server.The precision and determinism properties of Transact-SQLTransact-SQL functions are determined automatically by SQL ServerSQL Server. O acesso a dados e as propriedades de determinismo de funções CLR podem ser especificadas pelo usuário.The data access and determinism properties of CLR functions can be specified by the user. Para obter mais informações, consulte visão geral do CLR Integration atributos personalizados.For more information, see Overview of CLR Integration Custom Attributes.

Para exibir os valores atuais para essas propriedades, use OBJECTPROPERTYEX.To display the current values for these properties, use OBJECTPROPERTYEX.

As funções devem ser criadas com a associação de esquema para serem determinísticas.Functions must be created with schema binding to be deterministic.

Uma coluna computada que invoca uma função definida pelo usuário pode ser usada em um índice quando a função definida pelo usuário tem os seguintes valores de propriedades:A computed column that invokes a user-defined function can be used in an index when the user-defined function has the following property values:

  • IsDeterministic = trueIsDeterministic = true

  • IsSystemVerified = true (a menos que a coluna computada seja persistida)IsSystemVerified = true (unless the computed column is persisted)

  • UserDataAccess = falseUserDataAccess = false

  • SystemDataAccess = falseSystemDataAccess = false

    Para obter mais informações, consulte Indexes on Computed Columns.For more information, see Indexes on Computed Columns.

Chamando procedimentos armazenados estendidos de funçõesCalling Extended Stored Procedures from Functions

O procedimento armazenado estendido, quando chamado de dentro de uma função, não pode retornar conjuntos de resultados ao cliente.The extended stored procedure, when it is called from inside a function, cannot return result sets to the client. Quaisquer APIs ODS que retornam conjuntos de resultados ao cliente retornarão FAIL.Any ODS APIs that return result sets to the client will return FAIL. O procedimento armazenado estendido pode conectar-se novamente a uma instância do SQL ServerSQL Server. No entanto, ele não deve tentar unir a mesma transação como a função que invocou o procedimento armazenado estendido.The extended stored procedure could connect back to an instance of SQL ServerSQL Server; however, it should not try to join the same transaction as the function that invoked the extended stored procedure.

Semelhante a invocações de um procedimento armazenado ou em lotes, o procedimento armazenado estendido será executado no contexto da conta de segurança do Windows sob a qual o SQL ServerSQL Server está em execução.Similar to invocations from a batch or stored procedure, the extended stored procedure will be executed in the context of the Windows security account under which SQL ServerSQL Server is running. O proprietário do procedimento armazenado deve considerar isso ao fornecer permissão EXECUTE para usuários no procedimento.The owner of the stored procedure should consider this when giving EXECUTE permission on it to users.

Limitações e restriçõesLimitations and Restrictions

Funções definidas pelo usuário não podem ser usadas para executar ações que modificam o estado do banco de dados.User-defined functions cannot be used to perform actions that modify the database state.

As funções definidas pelo usuário não podem conter uma cláusula OUTPUT INTO que tenha uma tabela como seu destino.User-defined functions cannot contain an OUTPUT INTO clause that has a table as its target.

As seguintes instruções do Service BrokerService Broker não podem ser incluídas na definição de uma função Transact-SQLTransact-SQL definida pelo usuário:The following Service BrokerService Broker statements cannot be included in the definition of a Transact-SQLTransact-SQL user-defined function:

  • BEGIN DIALOG CONVERSATIONBEGIN DIALOG CONVERSATION

  • END CONVERSATIONEND CONVERSATION

  • GET CONVERSATION GROUPGET CONVERSATION GROUP

  • MOVE CONVERSATIONMOVE CONVERSATION

  • RECEIVERECEIVE

  • SENDSEND

    Funções definidas pelo usuário podem ser aninhadas, isto é, uma função definida pelo usuário pode chamar outra.User-defined functions can be nested; that is, one user-defined function can call another. O nível de aninhamento é incrementado quando a execução da função é iniciada, e reduzido quando a execução da função chamada é concluída.The nesting level is incremented when the called function starts execution, and decremented when the called function finishes execution. Até 32 níveis de funções definidas pelo usuário podem ser aninhados.User-defined functions can be nested up to 32 levels. Se o máximo de níveis de aninhamento for excedido haverá falha em toda a cadeia de funções da chamada de aninhamento.Exceeding the maximum levels of nesting causes the whole calling function chain to fail. Qualquer referência a um código gerenciado de uma função definida pelo usuário do Transact-SQLTransact-SQL é contada como um nível em relação ao limite de 32 níveis de aninhamento.Any reference to managed code from a Transact-SQLTransact-SQL user-defined function counts as one level against the 32-level nesting limit. Os métodos invocados a partir do código gerenciado não são contados em relação a esse limite.Methods invoked from within managed code do not count against this limit.

Usando a ordem de classificação em funções CLR com valor de tabelaUsing Sort Order in CLR Table-valued Functions

Ao usar a cláusula ORDER em funções CLR com valor de tabela, siga estas diretrizes:When using the ORDER clause in CLR table-valued functions, follow these guidelines:

  • Você deve garantir que os resultados sejam sempre ordenados na ordem especificada.You must ensure that results are always ordered in the specified order. Se os resultados não estiverem na ordem especificada, o SQL ServerSQL Server gerará uma mensagem de erro quando a consulta for executada.If the results are not in the specified order, SQL ServerSQL Server will generate an error message when the query is executed.

  • Se uma cláusula ORDER estiver especificada, a saída da função com valor de tabela deverá ser ordenada de acordo com o agrupamento da coluna (explícito ou implícito).If an ORDER clause is specified, the output of the table-valued function must be sorted according to the collation of the column (explicit or implicit). Por exemplo, se o agrupamento da coluna for chinês (especificado no DDL para a função com valor de tabela ou obtido do agrupamento do banco de dados), os resultados retornados deverão ser ordenados de acordo com as regras de classificação do chinês.For example, if the column collation is Chinese (either specified in the DDL for the table-valued function or obtained from the database collation), the returned results must be sorted according to Chinese sorting rules.

  • A cláusula ORDER, se especificada, é sempre verificada pelo SQL ServerSQL Server ao retornar resultados, quer ela seja usada ou não pelo processador de consultas para executar otimizações adicionais.The ORDER clause, if specified, is always verified by SQL ServerSQL Server while returning results, whether or not it is used by the query processor to perform further optimizations. Use a cláusula ORDER apenas se você souber que ela é útil para o processador de consultas.Only use the ORDER clause if you know it is useful to the query processor.

  • O processador de consultas do SQL ServerSQL Server beneficia-se automaticamente da cláusula ORDER nos seguintes casos:The SQL ServerSQL Server query processor takes advantage of the ORDER clause automatically in following cases:

    • Consultas de inserção em que a cláusula ORDER é compatível com um índice.Insert queries where the ORDER clause is compatible with an index.

    • Cláusulas ORDER BY que são compatíveis com a cláusula ORDER.ORDER BY clauses that are compatible with the ORDER clause.

    • Agregações, em que GROUP BY é compatível com a cláusula ORDER.Aggregates, where GROUP BY is compatible with ORDER clause.

    • Agregações DISTINCT em que as colunas distintas são compatíveis com a cláusula ORDER.DISTINCT aggregates where the distinct columns are compatible with the ORDER clause.

    A cláusula ORDER não garante resultados ordenados quando uma consulta SELECT é executada, a menos que ORDER BY também esteja especificado na consulta.The ORDER clause does not guarantee ordered results when a SELECT query is executed, unless ORDER BY is also specified in the query. Consulte function_order_columns ( Transact-SQL ) para obter informações sobre como consultar colunas incluídas na ordem de classificação para as funções com valor de tabela.See sys.function_order_columns (Transact-SQL) for information on how to query for columns included in the sort-order for table-valued functions.

MetadadosMetadata

A tabela a seguir lista as exibições do catálogo do sistema que você pode usar para retornar metadados sobre funções definidas pelo usuário.The following table lists the system catalog views that you can use to return metadata about user-defined functions.

Exibição do sistemaSystem View DescriptionDescription
sys.sql_modulessys.sql_modules Consulte o exemplo E, na seção exemplos abaixo.See example E in the Examples section below.
sys.assembly_modulessys.assembly_modules Exibe informações sobre funções CLR definidas pelo usuário.Displays information about CLR user-defined functions.
sys.parameterssys.parameters Exibe informações sobre os parâmetros definidos em funções definidas pelo usuário.Displays information about the parameters defined in user-defined functions.
sys.sql_expression_dependenciessys.sql_expression_dependencies Exibe os objetos subjacentes referenciados por uma função.Displays the underlying objects referenced by a function.

PermissõesPermissions

Requer a permissão CREATE FUNCTION no banco de dados e a permissão ALTER no esquema no qual a função está sendo criada.Requires CREATE FUNCTION permission in the database and ALTER permission on the schema in which the function is being created. Se a função especificar um tipo definido pelo usuário, a permissão EXECUTE será exigida no tipo.If the function specifies a user-defined type, requires EXECUTE permission on the type.

ExemplosExamples

A.A. Usando uma função definida pelo usuário com valor escalar que calcula a semana ISOUsing a scalar-valued user-defined function that calculates the ISO week

O exemplo a seguir cria a função definida pelo usuário ISOweek.The following example creates the user-defined function ISOweek. Essa função usa um argumento de data e calcula o número da semana ISO.This function takes a date argument and calculates the ISO week number. Para que essa função calcule corretamente, SET DATEFIRST 1 deve ser invocado antes da função ser chamada.For this function to calculate correctly, SET DATEFIRST 1 must be invoked before the function is called.

O exemplo também mostra como usar o EXECUTE AS cláusula para especificar o contexto de segurança no qual um procedimento armazenado pode ser executado.The example also shows using the EXECUTE AS clause to specify the security context in which a stored procedure can be executed. No exemplo, a opção CALLER especifica que o procedimento será executado no contexto do usuário que o chama.In the example, the option CALLER specifies that the procedure will be executed in the context of the user that calls it. As outras opções que podem ser especificadas são SELF, OWNER e user_name.The other options that you can specify are SELF, OWNER, and user_name.

Esta é a chamada da função.Here is the function call. Observe que DATEFIRST está definido como 1.Notice that DATEFIRST is set to 1.

CREATE FUNCTION dbo.ISOweek (@DATE datetime)  
RETURNS int  
WITH EXECUTE AS CALLER  
AS  
BEGIN  
     DECLARE @ISOweek int;  
     SET @ISOweek= DATEPART(wk,@DATE)+1  
          -DATEPART(wk,CAST(DATEPART(yy,@DATE) as CHAR(4))+'0104');  
--Special cases: Jan 1-3 may belong to the previous year  
     IF (@ISOweek=0)   
          SET @ISOweek=dbo.ISOweek(CAST(DATEPART(yy,@DATE)-1   
               AS CHAR(4))+'12'+ CAST(24+DATEPART(DAY,@DATE) AS CHAR(2)))+1;  
--Special case: Dec 29-31 may belong to the next year  
     IF ((DATEPART(mm,@DATE)=12) AND   
          ((DATEPART(dd,@DATE)-DATEPART(dw,@DATE))>= 28))  
          SET @ISOweek=1;  
     RETURN(@ISOweek);  
END;  
GO  
SET DATEFIRST 1;  
SELECT dbo.ISOweek(CONVERT(DATETIME,'12/26/2004',101)) AS 'ISO Week';  

Aqui está o conjunto de resultados.Here is the result set.

ISO Week  
----------------  
52  

B.B. Criando uma função com valor de tabela embutidaCreating an inline table-valued function

O exemplo a seguir retorna uma função com valor de tabela embutida no banco de dados AdventureWorks2012AdventureWorks2012.The following example returns an inline table-valued function in the AdventureWorks2012AdventureWorks2012 database. Ela retorna três colunas ProductID, Name e a agregação dos totais acumulados no ano por loja como YTD Total para cada produto vendido para a loja.It returns three columns ProductID, Name and the aggregate of year-to-date totals by store as YTD Total for each product sold to the store.

CREATE FUNCTION Sales.ufn_SalesByStore (@storeid int)  
RETURNS TABLE  
AS  
RETURN   
(  
    SELECT P.ProductID, P.Name, SUM(SD.LineTotal) AS 'Total'  
    FROM Production.Product AS P   
    JOIN Sales.SalesOrderDetail AS SD ON SD.ProductID = P.ProductID  
    JOIN Sales.SalesOrderHeader AS SH ON SH.SalesOrderID = SD.SalesOrderID  
    JOIN Sales.Customer AS C ON SH.CustomerID = C.CustomerID  
    WHERE C.StoreID = @storeid  
    GROUP BY P.ProductID, P.Name  
);  
GO  

Para invocar a função, execute esta consulta.To invoke the function, run this query.

SELECT * FROM Sales.ufn_SalesByStore (602);  

C.C. Criando uma função com valor de tabela de várias instruçõesCreating a multi-statement table-valued function

O exemplo a seguir cria a função com valor de tabela fn_FindReports(InEmpID) no banco de dados AdventureWorks2012.The following example creates the table-valued function fn_FindReports(InEmpID) in the AdventureWorks2012 database. Quando fornecida com uma ID de funcionário válida, a função retorna uma tabela que corresponde a todos os funcionários subordinados ao funcionário direta ou indiretamente.When supplied with a valid employee ID, the function returns a table that corresponds to all the employees that report to the employee either directly or indirectly. A função usa uma CTE (expressão de tabela comum) recursiva para produzir a lista hierárquica de funcionários.The function uses a recursive common table expression (CTE) to produce the hierarchical list of employees. Para obter mais informações sobre CTEs recursivas, consulte com common_table_expression ( Transact-SQL ) .For more information about recursive CTEs, see WITH common_table_expression (Transact-SQL).

CREATE FUNCTION dbo.ufn_FindReports (@InEmpID INTEGER)  
RETURNS @retFindReports TABLE   
(  
    EmployeeID int primary key NOT NULL,  
    FirstName nvarchar(255) NOT NULL,  
    LastName nvarchar(255) NOT NULL,  
    JobTitle nvarchar(50) NOT NULL,  
    RecursionLevel int NOT NULL  
)  
--Returns a result set that lists all the employees who report to the   
--specific employee directly or indirectly.*/  
AS  
BEGIN  
WITH EMP_cte(EmployeeID, OrganizationNode, FirstName, LastName, JobTitle, RecursionLevel) -- CTE name and columns  
    AS (  
        -- Get the initial list of Employees for Manager n
        SELECT e.BusinessEntityID, e.OrganizationNode, p.FirstName, p.LastName, e.JobTitle, 0   
        FROM HumanResources.Employee e   
INNER JOIN Person.Person p   
ON p.BusinessEntityID = e.BusinessEntityID  
        WHERE e.BusinessEntityID = @InEmpID  
        UNION ALL  
        -- Join recursive member to anchor
        SELECT e.BusinessEntityID, e.OrganizationNode, p.FirstName, p.LastName, e.JobTitle, RecursionLevel + 1   
        FROM HumanResources.Employee e   
            INNER JOIN EMP_cte  
            ON e.OrganizationNode.GetAncestor(1) = EMP_cte.OrganizationNode  
INNER JOIN Person.Person p   
ON p.BusinessEntityID = e.BusinessEntityID  
        )  
-- copy the required columns to the result of the function   
   INSERT @retFindReports  
   SELECT EmployeeID, FirstName, LastName, JobTitle, RecursionLevel  
   FROM EMP_cte   
   RETURN  
END;  
GO  
-- Example invocation  
SELECT EmployeeID, FirstName, LastName, JobTitle, RecursionLevel  
FROM dbo.ufn_FindReports(1);   

GO  

D.D. Criando uma função CLRCreating a CLR function

O exemplo cria a função CLR len_s.The example creates CLR function len_s. Antes que a função seja criada, o assembly SurrogateStringFunction.dll é registrado no banco de dados local.Before the function is created, the assembly SurrogateStringFunction.dll is registered in the local database.

Aplica-se a: do SQL Server 2008SQL Server 2008 ao SQL Server 2017SQL Server 2017.Applies to: SQL Server 2008SQL Server 2008 through SQL Server 2017SQL Server 2017.

DECLARE @SamplesPath nvarchar(1024);  
-- You may have to modify the value of this variable if you have  
-- installed the sample in a location other than the default location.  
SELECT @SamplesPath = REPLACE(physical_name, 'Microsoft SQL Server\MSSQL13.MSSQLSERVER\MSSQL\DATA\master.mdf', 
                                              'Microsoft SQL Server\130\Samples\Engine\Programmability\CLR\')   
    FROM master.sys.database_files   
    WHERE name = 'master';  

CREATE ASSEMBLY [SurrogateStringFunction]  
FROM @SamplesPath + 'StringManipulate\CS\StringManipulate\bin\debug\SurrogateStringFunction.dll'  
WITH PERMISSION_SET = EXTERNAL_ACCESS;  
GO  

CREATE FUNCTION [dbo].[len_s] (@str nvarchar(4000))  
RETURNS bigint  
AS EXTERNAL NAME [SurrogateStringFunction].[Microsoft.Samples.SqlServer.SurrogateStringFunction].[LenS];  
GO  

Para obter um exemplo de como criar uma função com valor de tabela do CLR, consulte CLR Table-Valued funções.For an example of how to create a CLR table-valued function, see CLR Table-Valued Functions.

E.E. Exibindo a definição de Transact-SQLTransact-SQL funções definidas pelo usuárioDisplaying the definition of Transact-SQLTransact-SQL user-defined functions

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

A definição de funções criadas com a opção ENCRYPTION não pode ser exibida usando sys.sql_modules; no entanto, outras informações sobre as funções criptografadas são exibidas.The definition of functions created by using the ENCRYPTION option cannot be viewed by using sys.sql_modules; however, other information about the encrypted functions is displayed.

Consulte TambémSee Also

ALTER FUNCTION (Transact-SQL) ALTER FUNCTION (Transact-SQL)
Remover função ( Transact-SQL ) DROP FUNCTION (Transact-SQL)
OBJECTPROPERTYEX ( Transact-SQL ) OBJECTPROPERTYEX (Transact-SQL)
sys.sql_modules (Transact-SQL) sys.sql_modules (Transact-SQL)
sys.assembly_modules (Transact-SQL) sys.assembly_modules (Transact-SQL)
EXECUTE (Transact-SQL) EXECUTE (Transact-SQL)
Funções CLR definidas pelo usuário CLR User-Defined Functions
EVENTDATA (Transact-SQL) EVENTDATA (Transact-SQL)
Criar política de segurança ( Transact-SQL )CREATE SECURITY POLICY (Transact-SQL)