vertica用户自定义扩展介绍

用户自定义扩展介绍

vertica允许用户使用C++，Python，Java和R编程语言开发自己的分析或数据加载工具，当要使用SQL进行的数据处理类型困难或缓慢时，它们很有用。

包括以下UDx类型：

用户定义的聚合函数（UDAFs）
分析函数（UDAnF）
标量函数（UDSF）
转换函数（UDTF）
用户定义的加载函数（UDL）

用户定义的聚合函数（UDAFs）

聚合函数对一组值执行一个运算并返回一个值。 Vertica提供内置标准的聚合功能，例如AVG，MAX和MIN。用户定义的聚合函数（UDAF）提供类似的功能：

支持单个输入列（或一组值），并提供单个输出列。
支持RLE解压。RLE输入在发送到UDAF之前先被解压缩。
支持使用GROUP BY和HAVING子句。

以下限制适用于UDAF：

仅适用于C ++。
不能与相关子查询一起使用。

关于UDAFs类以及C++ API，在使用时请参考官方文档中的描述。

分析函数（UDAnF）

用户定义的分析函数（UDAnF）用于分析。与用户定义的标量函数（UDSF）一样，UDAnF必须为读取的每一行数据输出一个值，并且参数不能超过1600个。

与UDSF不同，UDAnF的输入阅读器和输出阅读器可以独立进行升级。通过此功能，您可以创建UDAnF，在其中对多个数据行计算输出值。通过独立地推进读取器和写入器，您可以创建类似于内置分析功能的功能，例如LAG，该功能使用先前行中的数据为当前行输出值。

关于UDAnF类以及C++ 和JAVA API，在使用时请参考官方文档中的描述。

标量函数（UDSF）

用户定义的标量函数（UDSF）对于读取的每一行数据返回一个值。可以在允许使用内置Vertica功能的任何地方使用UDSF 。通常，您会开发UDSF来执行过于复杂或太慢而无法使用SQL语句和函数执行的数据操作。UDSF还可让您使用Vertica中第三方库提供的分析功能，同时仍保持高性能。

UDSF必须为每个输入行返回一个值（除非它会产生错误）。如果未在Fenced Mode下运行，则无法为行返回值，这不仅将导致错误的结果，并可能破坏Vertica服务器的稳定性。

UDSF的参数不能超过1600。

关于UDSF类以及C++ ，JAVA ，Python，R API，在使用时请参考官方文档中的描述。

转换函数（UDTF）

用户定义的转换函数（UDTF）使您可以将一个数据表转换为另一个表。它读取一个或多个参数（视为一行数据），并返回零个或多个由一个或多个列组成的数据行。UDTF可以产生任意数量的行作为输出。但是，它输出的每一行都必须完整。前进到下一行而未为每一列添加值都会产生错误的结果。

输出表的schema不需要与输入表的schema相对应–它们可以完全不同。UDTF可以为每行输入返回任意数量的输出行。

UDTF只能在仅包含UDTF调用和必需的OVER子句的SELECT列表中使用。多阶段UDTF可以使用分区列（PARTITION BY），而其他UDTF则不能。

UDTF在语句中与GROUP BY和ORDER BY结合使用时，在GROUP BY之后但在最终的ORDER BY之前运行。ORDER BY子句只能包含窗口分区子句中的列或表达式。

UDTF最多可以容纳1600个参数（输入列）。尝试将更多参数传递给UDTF会导致错误。

关于UDTF类以及C++ ，JAVA ，Python，R API，在使用时请参考官方文档中的描述。

用户定义的负载（UDL）

COPY提供了广泛的选项和设置来控制如何加载数据。但是，您可能会发现这些选项不适合您要执行的数据加载类型。用户定义的加载（UDL）功能使您可以开发一个或多个函数来更改COPY语句的操作方式。您可以使用Vertica SDK 创建自定义库，以处理加载过程中的各个步骤。。

您在开发过程中使用三种类型的UDL函数，每一种用于数据加载过程的每个阶段：

用户定义的源（UDSource）：控制COPY如何获取加载到数据库的数据。例如，COPY可能通过HTTP或CURL来获取数据。最多只能有一个UDSource从文件或输入流读取数据。您的UDSource可以从多个源中读取，但是COPY仅调用一个UDSource。

API支持： C ++，Java
用户定义的过滤器（UDFilter）：预处理数据。例如，筛选器可能会解压缩文件或将UTF-16转换为UTF-8。您可以将多个用户定义的过滤器链接在一起，例如解压缩然后进行转换。

API支持： C ++，Java，Python
用户定义的解析器（UDParser）：最多一个解析器将数据解析为可以插入表中的元组。例如，解析器可以从类似XML的格式提取数据。您可以选择定义一个用户定义的分块器（仅限UDChunker，仅C ++），以使解析器执行并行解析。

API支持： C ++，Java，Python

完成最后一步后，COPY将数据插入表中，如果格式不正确，则将其拒绝。

关于UDL的三种类型的函数以及C++ ，JAVA ，Python API，在使用时请参考官方文档中的描述。

使用用户自定义扩展

加载UDxs

用户定义的扩展（UDx）包含在库中，一个库可以包含多个UDx。要将UDx添加到Vertica，您必须：

加载库（每个库加载）。
声明每个UDx（每个UDx声明一次）。

如果使用的是用Java编写的UDx，则还必须设置Java运行时环境。

加载库

要将库部署到Vertica数据库，有一下步骤：

将您的函数包含的UDx共享库文件.so文件，Python文件或JAR 文件复制到Vertica群集上的某一节点上。无需将其复制到集群的每个节点。
连接到包含库的节点（例如，使用vsql）。
使用CREATE LIBRARY语句将库添加到数据库目录中，语法如下：

CREATE LIBRARY libname AS '/path_to_lib/filename' LANGUAGE 'language';

libname是您要用来引用库的名称。/path_to_lib/filename是复制到主机的库或JAR文件的标准路径。语言是实现该UDx的语言。
例如，如果您创建了一个名为TokenizeStringLib.jar的JAR文件并将其复制到dbadmin帐户的主目录中，则可以使用以下命令来加载该库：

CREATE LIBRARY tokenizelib AS '/home/dbadmin/TokenizeStringLib.jar' LANGUAGE 'Java';

声明UDx

加载库后，使用SQL语句（例如CREATE FUNCTION和CREATE SOURCE）定义单个UDx 。这些语句将SQL函数名称分配给库中的扩展类。他们将UDx添加到数据库目录中，并在数据库重新启动后保持可用。

所使用的语句取决于您要声明的UDx的类型，如下表所示：

UDx Type	SQL Statement
Aggregate Function (UDAF)	CREATE AGGREGATE FUNCTION
Analytic Function (UDAnF)	CREATE ANALYTIC FUNCTION
Scalar Function (UDSF)	CREATE FUNCTION (UDF)
Transform Function (UDTF)	CREATE TRANSFORM FUNCTION
Load (UDL): Source	CREATE SOURCE
Load (UDL): Filter	CREATE FILTER
Load (UDL): Parser	CREATE PARSER

将UDx添加到数据库后，可以在SQL语句中使用自定义扩展名。数据库超级用户可以为用户授予对UDx的访问权限。

调用UDx时，Vertica在群集中的每个节点上创建UDx类的实例，并为其提供需要处理的数据。

如果您使用的是用Java编写的UDx，您必须在群集中的每个主机上安装Java虚拟机（JVM），以使Vertica能够执行Java UDx。
在Vertica群集上安装Java 分为两个步骤：

在集群中的所有主机上安装Java runtime。
设置JavaBinaryForUDx配置参数以告诉Vertica Java可执行文件的位置。
如：ALTER DATABASE mydb SET JavaBinaryForUDx = '/usr/bin/java';

隔离模式(Fenced Mode)

用C ++编程语言编写的用户定义扩展（UDx）可以选择以非隔离模式运行，这意味着可以直接在Vertica进程中运行。由于它们在Vertica中运行，因此非隔离模式的UDx几乎没有开销，并且执行速度几乎与Vertica自己的内置功能一样快。但是，由于它们直接在Vertica中运行，因此其代码中的任何错误（例如内存泄漏）都可能破坏Vertica主进程的稳定性，从而导致一个或多个数据库节点崩溃。

您可以选择以隔离模式运行大多数C ++ UDx，该模式在Vertica主进程之外运行UDx代码。在隔离模式下运行时崩溃的UDx代码不会影响Vertica主进程。在隔离模式下运行UDx代码时，对性能的影响很小。与非隔离模式相比，使用隔离模式平均可增加执行时间约10％。

除用户定义的聚合函数外，所有C ++ UDx当前都可以使用隔离模式。用Python，R和Java编程语言开发的所有UDx必须在隔离模式下运行，因为Python，R和Java的runtimes不能直接在Vertica进程中运行。

使用隔离模式不会影响UDx的开发。默认情况下，支持隔离模式的UDx启用隔离模式。可以选择在CREATE FUNCTION时使用NOT FENCED修饰符，以禁用该函数的隔离模式。另外，您可以使用ALTER FUNCTION命令在任何支持隔离模式的C ++ UDx上启用或禁用隔离模式。

隔离模式的日志记录

日志存储在数据库catalog目录下的UDxLogs目录下。

隔离模式的一些配置参数

隔离模式支持三个配置参数：

FencedUDxMemoryLimitMB
用于Fenced Mode进程的最大内存大小（以MB为单位）。默认值为-1（无限制）。如果超出此限制，则终止进程。
ForceUDxFencedMode
设置为1时，即使其定义指定为NOT FENCED，也强制所有支持隔离模式的UDx以隔离模式运行。默认值为0（禁用）。
UDxFencedBlockTimeout
Vertica服务器等待UDx返回的最大时间（以秒为单位），超过该值没有返回，UDx就会中止，错误码为3399。默认值为60。

更新UDx库

在两种情况下，需要更新已经部署的库：

将Vertica升级到包含对SDK API所做更改的新版本后。
为了使您的库能够使用新的服务器版本，您需要使用新版本的SDK重新编译它们。
对UDx进行更改后，您想部署使用这些更改。
在更新UDx库之前，您需要确定是否更改了库中包含的任何函数的名称。如果有，则需要在更新库之前从Vertica目录中删除这些函数。

在主要版本之间升级时需要更新UDx库。例如，如果从9.0版本升级到9.1，则需要更新UDx库。

升级前步骤

必须重新编译与新版本的Vertica服务器不兼容的所有UDx库。如果您从第三方（例如通过Vertica Marketplace）获得了UDx库，则需要查看是否已发布新版本。

如果您自己开发了UDx（或者由开发者提供了UDx的源代码），则必须：

使用新版本的Vertica SDK 重新编译UDx库。
部署库的新版本。

确定UDx名称是否已更改

对UDx进行以下任何更改都会更改其名称：

更改函数接受的参数数量或任何参数接受的数据类型（不包括多态函数）。
更改任何返回值或输出列的数量或数据类型。
更改Vertica用于创建功能代码实例的工厂类的名称。
更改函数的空处理或波动行为。
从库中完全删除了函数的工厂类。

部署新版本的UDx库

如果要部署用C ++或Java开发的UDx库，则必须使用当前版本的Vertica SDK进行编译。
将UDx的库文件（用C ++开发的.so库文件，用Python 开发的.py库文件或用Java开发的.jar库文件）或R源文件复制到Vertica 数据库中的主机。
使用vsql连接到主机。
如果您更改了共享库中任何UDx的名称，则必须使用DROP语句（例如DROP FUNCTION或DROP SOURCE）删除它们。
使用ALTER LIBRARY语句更新UDx库定义。例如，如果要使用dbadmin用户主目录中的ScalarFunctions-2.0.so文件更新名为ScalarFunctions的库，则可以使用以下命令：
ALTER LIBRARY ScalarFunctions AS'/home/dbadmin/ScalarFunctions-2.0.so';
将UDx库定义更新为使用共享库的新版本之后，使用UDx库中的类定义的UDx将开始使用新的共享库文件，而无需进行任何其他更改。
如果必须删除任何函数，请使用库中工厂类定义的新名称重新创建它们。

本文整理自：
Using User-Defined Extensions