CREATE [OR REPLACE] FUNCTION

使用 CREATE FUNCTION 命令创建用户自定义函数。 CREATE OR REPLACE FUNCTION 创建一个函数，或用新的对象文件、返回值、函数行为或日志级别替换现有的同名函数。

概要

创建新用户定义函数的语法：

CREATE [OR REPLACE] FUNCTION function_name(argument_types)
RETURNS return_type LANGUAGE CPP PARAMETER STYLE NPSGENERIC
[FENCED | NOT FENCED] [DETERMINISTIC | NOT DETERMINISTIC]
[RETURNS NULL ON NULL INPUT | CALLED ON NULL INPUT]
[MAXIMUM MEMORY mem] [LOGMASK <MASK>]
[NO DEPENDENCIES| DEPENDENCIES deplibs]
[API VERSION [ 1 | 2 ]]
[ENVIRONMENT 'name' = 'value', 'name2' = 'value2']
[TABLE, TABLE FINAL ALLOWED | TABLE ALLOWED | TABLE FINAL ALLOWED]
[PARALLEL ALLOWED | PARALLEL NOT ALLOWED]
[EXTERNAL CLASS NAME 'class_name']
[EXTERNAL HOST OBJECT 'host_object_filename']
[EXTERNAL SPU OBJECT 'SPU_object_filename']

输入

CREATE [OR REPLACE] FUNCTION 命令接受以下输入：

表 1. 创建 [OR REPLACE] 函数 inputs
输入	描述
`FUNCTION_NAME`	指定要创建的函数名称。这是 SQL 标识，用于在 SQL 表达式中调用函数。名称必须符合关键字和标识符的命名标准，详情请参见《IBM Netezza数据库用户指南》。如果函数已存在，则不能使用 CREATE OR REPLACE 命令更改名称。对于支持多模式的系统，可以指定schema.function格式的名称，在当前数据库的不同模式中创建函数。不能在不同的数据库中创建函数。
`参数类型`	指定完全指定的函数参数数据类型列表。支持所有Netezza Performance Server数据类型。字符串必须包含尺寸或 ANY（通用尺寸）。 NUMERIC 类型必须包含精度和刻度，对于通用尺寸则必须包含 ANY。您还可以指定 VARARGS 值来创建一个变量参数集合，用户最多可以输入 64 个任何支持数据类型的值。 VARARGS 是一个互斥值，不能在列表中指定任何其他参数。不能更改参数列表或大小。您可以从参数列表中移除 VARARGS，或将其添加到本来为空的参数列表中。使用此命令不能更改参数列表。如果函数已经存在，则不能使用 CREATE OR REPLACE 命令更改参数类型列表。您还可以使用 CREATE OR REPLACE 更改 UDF 参数类型的某些方面，例如，您可以更改字符串的大小或数值的精度和比例。
返回返回`类型`	return_type 值是一个完全指定的参数和类型。它遵循与 argument_types 相同的规则。如果 API 版本为 2，返回类型也可以是 TABLE(name type,name2 type2, ...) 或 TABLE(ANY) 指定表格函数。
中文	指定函数使用的编程语言。默认值和目前唯一支持的值是 CPP (C++)。
PARAMETER STYLE	目前唯一支持的默认值是 NPSGENERIC。
FENCED NOT FENCED	指定函数是否在受保护地址空间（栅栏模式）的单独进程中执行。要创建取消围栏功能，您必须拥有取消围栏管理权限。
[确定性 \| 非确定性]	DETERMINISTIC 表示 UDF 是一个纯函数，在参数值相同的情况下总是返回相同的值，并且没有副作用。系统可能会将具有相同参数列表的确定性 UDF 的多个实例视为共同子表达式消除（CSE）的候选实例。默认值为 DETERMINISTIC。如果函数是确定的，则在语句准备时调用一次，而不是每行调用一次，条件是以下任一条件为真：如果输入为空，且一个或多个参数为空（字面 NULL），则返回空。它有所有不变的论点。如果参数是 SQL 字面量，或者是在语句准备时评估一次而不是每行评估一次的 UDF 或内置函数的结果，那么该参数就是常量。
[空输入时返回空值 \| 空输入时调用空值] [空输入时返回空值 \| 空输入时调用空值	RETURNS NULL ON NULL INPUT 表示当函数的任何参数为 NULL 时，函数总是返回 NULL。如果指定了该参数，当参数为 NULL 时，函数不会被执行，而是自动假定结果为 NULL。 CALLED ON NULL INPUT（默认值）表示当函数的某些参数为 NULL 时，函数被正常调用。然后，函数创建者有责任在必要时检查 NULL 值，并做出适当的响应。有关此设置的查询优化效果的更多信息，请参阅Netezza Performance Server查询优化和 UDX 调用。
最大内存	指定函数的潜在内存使用指示。大小值可以是空值，也可以是由数字和字母 b（字节）、k（千字节）、m（兆字节）或 g（千兆字节）组成的值。例如，有效值可以是 "0"、1k"、100k"、1g"或10m"。缺省值为 0。
LOGMASK`屏蔽`	指定功能的日志控制级别。有效值为 "无"、"DEBUG "和 "TRACE"，或以逗号分隔的 DEBUG 和 TRACE 组合。
依赖项`deplibs`	指定 UDX 的用户自定义共享库依赖关系的可选列表。您可以指定一个库名或以逗号分隔的库名列表。
应用程序版本 [1 \| 2]	指定聚合体使用的 UDX 接口版本。 API 版本必须与主机和 SPU 对象文件的编译版本一致。缺省值为 1。如果包含版本 2 的编译对象，则必须指定 API VERSION 2。
环境	指定函数执行时可用的名-值对。您可以指定多个以逗号分隔的名-值对。要变更一个或多个环境对的现有集合，必须指定所有环境设置；ALTER 命令会将当前列表替换为 ALTER 命令中指定的列表。
表格，表格最终允许允许表格表格最后允许	指定控制如何调用用户定义表函数的选项。 TABLE, TABLE FINAL ALLOWED 选项指定可以通过使用 TABLE(func())、TABLE WITH FINAL(func())或两种情况调用表函数。您还可以指定 TABLE ALLOWED 或 TABLE FINAL ALLOWED，以允许使用其中一种表格调用用户定义的表格函数。 FINAL 表示在处理完所有输入行后才调用表格函数，因此可以输出更多行。
允许并行	指定用户定义的表函数可以在主机或 SPU 上调用，由优化器自行决定。
不允许并行	指定表格函数始终在主机上调用，或由优化器自行决定在一个选定的 SPU 上调用。
外部类名`"class_name`	指定实现函数的 C++ 类的名称。该类必须派生自 Udf 基类，并且必须实现一个静态方法来实例化该类的一个实例。
外部主机对象`"host_object_filename`	指定主机执行编译对象的路径名。
外部 SPU`对象 "SPU_object_filename`	指定Linux®SPU 编译对象文件的路径名。为 "IBM® Netezza® 1000和 "Netezza 1000型号上的 "Rev10SPU 指定 "spu10编译对象。

输出

CREATE [OR REPLACE] FUNCTION 命令有以下输出：

表 2. 创建 [OR REPLACE] FUNCTION 输出
输出	描述
`CREATE FUNCTION`	命令成功后系统返回的信息。
`ERROR: User 'username' is not allowed to create/drop functions.`	如果用户账户没有创建功能权限，系统将返回此信息。
`ERROR: Synonym 'name' already exists`	如果存在与您为函数指定的名称相同的同义词，系统将返回此信息。
`ERROR: function name already exists with the same signature`	当您发出 CREATE FUNCTION 命令，而数据库中已存在具有相同名称和参数类型列表的函数时，将返回此错误。使用 CREATE OR REPLACE FUNCTION 代替。
`ERROR: function name already exists with the same signature`	如果存在与您为函数指定的名称相同的函数，系统将返回此信息。
`NOTICE: FunctionCreate: existing UDX name(argument_types) differs in size of string/numeric arguments`	该信息表明存在名称为该名称的 UDX，但为字符串或数字参数指定的尺寸不同。如果无意更改函数签名，请检查签名并确保其正确无误。
`ERROR: lookupLibrary: library libname does not exist`	如果系统无法找到指定为依赖关系的用户定义共享库，系统将返回的信息。
`ERROR: ProcedureCreate: Can't use version 2 features without specifying API VERSION 2 for udx_name`	该信息表明您为 SQL 命令指定了版本 2 选项，但没有在 SQL 命令中同时指定 API VERSION 2。
`ERROR: Version mismatch for function udx_name. Specified version 2, but provided version 1 object file`	编译后的对象文件使用第 1 版 API 支持，但 SQL 命令使用第 2 版功能。您必须创建第 2 版编译对象，或删除命令中指定第 2 版功能的选项。
`ERROR: Version mismatch for function udx_name. Specified version 1, but provided version 2 object file`	编译后的对象文件使用第 2 版 API 支持，但 SQL 命令使用第 1 版功能。您必须指定版本 1 的编译对象，或更改 ALTER 命令以指定版本 2 的语法。
`ERROR: Environment names can't be empty`	环境设置的`名称`值不能为空字符串。
`ERROR: type 'type' is not yet defined`	指定的返回类型不是已知的Netezza Performance Server数据类型。

描述

创建函数时，函数签名（即名称和参数类型列表）必须在数据库中唯一。在同一个数据库中，任何其他用户定义的函数或聚合函数都不能有相同的名称和参数类型列表。

使用 CREATE OR REPLACE 命令不能更改函数名称或参数类型列表。您可以更改参数类型的某些方面，例如更改字符串的大小或数值的精度和比例。要更改函数名称、参数类型列表或两者，必须放弃该函数，然后用新名称、参数类型列表或两者创建一个函数。

不能替换活动查询中正在使用的用户定义函数。活动查询事务完成后，Netezza Performance Server系统会处理 CREATE OR REPLACE FUNCTION 命令以更新函数。

需要权限

您必须是数据库管理员用户，拥有当前数据库，或在支持多模式的系统中拥有当前模式。其他用户必须拥有创建函数权限才能使用 CREATE FUNCTION 命令。此外，如果使用 CREATE OR REPLACE FUNCTION 更改 UDF，则必须拥有创建函数和更改 UDF 的权限才能更改它。要创建取消围栏功能，您必须拥有取消围栏管理权限。

注意：发出 CREATE FUNCTION 命令时，数据库会以用户 nz 的身份处理 HOST OBJECT 和 SPU OBJECT 文件。用户 nz 必须拥有对对象文件的读取权限，以及对从根目录到对象文件的路径中每个目录的读取和执行权限。

常用任务

使用 CREATE FUNCTION 命令创建一个新的用户定义函数，并成为该函数的所有者。您必须先创建函数 C++ 文件并使用 "nzudxcompile进行编译，然后才能使用此命令在Netezza Performance Server系统中注册函数。该函数被定义为当前数据库中的一个对象。

用途

以下是使用示例。

创建示例函数 "CustomerName（在创建用户定义函数中描述）：

MYDB.SCHEMA(MYUSER)=> CREATE FUNCTION CustomerName(varchar(64000))
RETURNS int4 LANGUAGE CPP PARAMETER STYLE npsgeneric
EXTERNAL CLASS NAME 'CCustomerName'
EXTERNAL HOST OBJECT '/home/nz/udx_files/customername.o_x86'
EXTERNAL SPU OBJECT '/home/nz/udx_files/customername.o_spu10'