UDTF（User Defined Timeseries Generating Function） 编写一个UDTF需要继承“org.apache.iotdb.db.query.udf.api.UDTF”类，并至少实现“beforeStart”方法和一种“transform”方法。 表2是所有可供用户实现的接口说明。 表2 接口说明 接口定义 描述 是否必须 void validate(UDFParameterValidator validator) throws Exception 在初始化方法“beforeStart”调用前执行，用于检测“UDFParameters”中用户输入的参数是否合法。 否 void beforeStart(UDFParameters parameters, UDTFConfigurations configurations) throws Exception 初始化方法，在UDTF处理输入数据前，调用用户自定义的初始化行为。用户每执行一次UDTF查询，框架就会构造一个新的UDF类实例，该方法在每个UDF类实例被初始化时调用一次。在每一个UDF类实例的生命周期内，该方法只会被调用一次。 是 void transform(Row row, PointCollector collector) throws Exception 该方法由框架调用。当在“beforeStart”中选择以“RowByRowAccessStrategy”的策略消费原始数据时，这个数据处理方法就会被调用。输入参数以“Row”的形式传入，输出结果通过“PointCollector”输出。需要在该方法内自行调用“collector”提供的数据收集方法，以决定最终的输出数据。 与“transform(RowWindow rowWindow, PointCollector collector) ”方法二选一 void transform(RowWindow rowWindow, PointCollector collector) throws Exception 该方法由框架调用。当在“beforeStart”中选择以“SlidingSizeWindowAccessStrategy”或者“SlidingTimeWindowAccessStrategy”的策略消费原始数据时，这个数据处理方法就会被调用。输入参数以“RowWindow”的形式传入，输出结果通过“PointCollector”输出。需要在该方法内自行调用“collector”提供的数据收集方法，以决定最终的输出数据。 与“transform(Row row, PointCollector collector)”方法二选一 void terminate(PointCollector collector) throws Exception 该方法由框架调用。该方法会在所有的“transform”调用执行完成后，在“beforeDestory”方法执行前被调用。在一个UDF查询过程中，该方法会且只会调用一次。需要在该方法内自行调用“collector”提供的数据收集方法，以决定最终的输出数据。 否 void beforeDestroy() UDTF的结束方法。此方法由框架调用，并且只会被调用一次，即在处理完最后一条记录之后被调用。 否 调用顺序： void validate(UDFParameterValidator validator) throws Exception void beforeStart(UDFParameters parameters, UDTFConfigurations configurations) throws Exception void transform(Row row, PointCollector collector) throws Exception或者void transform(RowWindow rowWindow, PointCollector collector) throws Exception void terminate(PointCollector collector) throws Exception void beforeDestroy() 框架每执行一次UDTF查询，都会构造一个全新的UDF类实例，查询结束时，对应的UDF类实例即被销毁，因此不同UDTF查询（即使是在同一个SQL语句中）UDF类实例内部的数据都是隔离的。可以在UDTF中维护一些状态数据，无需考虑并发对UDF类实例内部状态数据的影响。 使用方法： void validate(UDFParameterValidator validator) throws Exception “validate”方法能够对用户输入的参数进行验证。 在该方法中限制输入序列的数量和类型，检查用户输入的属性或者进行自定义逻辑的验证。 void beforeStart(UDFParameters parameters, UDTFConfigurations configurations) throws Exception “beforeStart”方法有以下作用： 帮助用户解析SQL语句中的UDF参数。 配置UDF运行时必要的信息，即指定UDF访问原始数据时采取的策略和输出结果序列的类型。 创建资源，比如建立外部链接，打开文件等。

UDFParameters UDFParameters的作用是解析SQL语句中的UDF参数（SQL中UDF函数名称后括号中的部分）。参数包括路径（及其序列类型）参数和字符串“key-value”对形式输入的属性参数。 例如： SELECT UDF(s1, s2, 'key1'='iotdb', 'key2'='123.45') FROM root.sg.d; 用法： void beforeStart(UDFParameters parameters, UDTFConfigurations configurations) throws Exception { // parameters for (PartialPath path : parameters.getPaths()) { TSDataType dataType = parameters.getDataType(path); // do something } String stringValue = parameters.getString("key1"); // iotdb Float floatValue = parameters.getFloat("key2"); // 123.45 Double doubleValue = parameters.getDouble("key3"); // null int intValue = parameters.getIntOrDefault("key4", 678); // 678 // do something // configurations // ...}

IoTDB支持的数据类型和编码 IoTDB支持如下几种数据类型和编码方式，参见表1。 表1 IoTDB支持的数据类型和编码 类型 说明 支持的编码 BOOLEAN 布尔值 PLAIN、RLE INT32 整型 PLAIN、RLE、TS_2DIFF、GORILLA、FREQ、ZIGZAG INT64 长整型 PLAIN、RLE、TS_2DIFF、GORILLA、FREQ、ZIGZAG FLOAT 单精度浮点数 PLAIN、RLE、TS_2DIFF、GORILLA、FREQ DOUBLE 双精度浮点数 PLAIN、RLE、TS_2DIFF、GORILLA、FREQ TEXT 字符串 PLAIN、DICTIONARY 父主题： 使用IoTDB

容量规格 ConfigNode容量规格 当创建新的存储组时，IoTDB默认为该存储组分配10000个槽位，数据写入时根据写入的设备名和时间值，分配或创建一个data region并挂载在某个槽位上。所以ConfigNode的内存容量占用跟存储组个数和该存储组持续写入的时间相关。 槽位分配相关对象 对象大小（字节） TTimePartitionSlot 4 TSeriesPartitionSlot 8 TConsensusGroupId 4 根据上表计算可得一个ConfigNode，如果创建一个存储组，持续运行10年，大约需要0.68G内存 : 10000(槽位) * 10（年）* 53 (分区) * （TTimePartitionSlot size + TSeriesPartitionSlot size + TConsensusGroupId size）= 0.68G IoTDBServer容量规格 IoTDB中数据以region分配在IoTDBServer上，region副本数默认是“3”，最终在IoTDBServer文件系统上表现为3个文件。上限为操作系统可存储文件个数最大值，对于Linux系统即是inode个数。

IoTDB结构 IoTDB套件由若干个组件构成，共同形成数据收集、数据写入、数据存储、数据查询、 数据可视化 、数据分析等一系列功能。 图1展示了使用IoTDB套件的全部组件形成的整体应用架构，IoTDB特指其中的时间序列数据库组件。 图1 IoTDB结构 用户可以通过JDBC/Session将来自设备传感器上采集的时序数据和服务器负载、CPU内存等系统状态数据、消息队列中的时序数据、应用程序的时序数据或者其他数据库中的时序数据导入到本地或者远程的IoTDB中。用户还可以将上述数据直接写成本地（或位于HDFS上）的TsFile文件。 用户可以将TsFile文件写入到HDFS上，进而满足Hadoop、Flink等数据处理任务的访问。 对于写入到HDFS或者本地的TsFile文件，可以利用TsFile-Hadoop或TsFile-Flink连接器，允许Hadoop或Flink进行数据处理。 对于分析的结果，可以写回成TsFile文件。 IoTDB和TsFile还提供了相应的客户端工具，满足用户以SQL形式、脚本形式和图形形式写入和查看数据的各种需求。 IoTDB服务包括IoTDBServer（DataNode）和ConfigNode两种角色。由于社区版角色名称DataNode和HDFS角色同名，因此将DataNode更名为IoTDBServer，如图2所示。 ConfigNode：管理角色，负责DataNode数据分片，负载均衡等。 IoTDBServer（DataNode）：存储角色，负责数据存储、查询和写入等功能。 图2 IoTDB分布式架构

IoTDB原理 根据属性层级、属性涵盖范围以及数据之间的从属关系，可将IoTDB数据模型表示为如图3所示的属性层级组织结构，即“电力集团层-电厂层-设备层-传感器层”。其中ROOT为根节点，传感器层的每一个节点为叶子节点。IoTDB的语法规定，ROOT节点到叶子节点的路径以“.”连接，以此完整路径命名IoTDB中的一个时间序列。例如，下图最左侧路径对应的时间序列名称为“ROOT.ln.wf01.wt01.status”。 图3 IoTDB数据模型

查看调测结果 IoTDB应用程序运行完成后，可通过IntelliJ IDEA运行结果查看应用程序运行情况。 JDBCExample样例程序运行结果如下所示： ...--------------------------Time root.sg.d1.s1 root.company.line2.device1.temperature root.company.line2.device1.speed root.company.line2.device2.speed root.company.line2.device2.status root.company.line1.device1.spin root.company.line1.device1.status root.company.line1.device2.temperature root.company.line1.device2.power root.sg1.d1.s3 root.sg1.d1.s1 root.sg1.d1.s2 0, null, null, null, null, null, null, null, null, null, 1.0, 1.0, 1.01, null, null, null, null, null, null, null, null, null, 1.0, 1.0, 1.02, null, null, null, null, null, null, null, null, null, 1.0, 1.0, 1.03, null, null, null, null, null, null, null, null, null, 1.0, 1.0, 1.04, null, null, null, null, null, null, null, null, null, 1.0, 1.0, 1.05, null, null, null, null, null, null, null, null, null, 1.0, 1.0, 1.06, null, null, null, null, null, null, null, null, null, 1.0, 1.0, 1.07, null, null, null, null, null, null, null, null, null, 1.0, 1.0, 1.08, null, null, null, null, null, null, null, null, null, 1.0, 1.0, 1.09, null, null, null, null, null, null, null, null, null, 1.0, 1.0, 1.010, null, null, null, null, null, null, null, null, null, 1.0, 1.0, 1.0----------------------------------------------------count(root.sg.d1.s1) count(root.company.line2.device1.temperature) count(root.company.line2.device1.speed) count(root.company.line2.device2.speed) count(root.company.line2.device2.status) count(root.company.line1.device1.spin) count(root.company.line1.device1.status) count(root.company.line1.device2.temperature) count(root.company.line1.device2.power) count(root.sg1.d1.s3) count(root.sg1.d1.s1) count(root.sg1.d1.s2) 8237, 1, 1, 1, 1, 1, 1, 1, 1, 101, 101, 101----------------------------------------------------Time count(root.sg.d1.s1) count(root.company.line2.device1.temperature) count(root.company.line2.device1.speed) count(root.company.line2.device2.speed) count(root.company.line2.device2.status) count(root.company.line1.device1.spin) count(root.company.line1.device1.status) count(root.company.line1.device2.temperature) count(root.company.line1.device2.power) count(root.sg1.d1.s3) count(root.sg1.d1.s1) count(root.sg1.d1.s2) 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 19, 19, 1920, 0, 0, 0, 0, 0, 0, 0, 0, 0, 20, 20, 2040, 0, 0, 0, 0, 0, 0, 0, 0, 0, 20, 20, 2060, 0, 0, 0, 0, 0, 0, 0, 0, 0, 20, 20, 2080, 0, 0, 0, 0, 0, 0, 0, 0, 0, 20, 20, 20-------------------------- FlinkIoTDBSink样例程序运行结果如下所示： ...19:53:41.532 [flink-akka.actor.default-dispatcher-9] DEBUG org.apache.flink.runtime.resourcemanager.StandaloneResourceManager - Received heartbeat from 5153e4ff24b25b13225f1bf67a4312d8.19:53:41.800 [flink-akka.actor.default-dispatcher-9] DEBUG org.apache.flink.runtime.jobmaster.JobMaster - Trigger heartbeat request.19:53:41.800 [flink-akka.actor.default-dispatcher-10] DEBUG org.apache.flink.runtime.taskexecutor.TaskExecutor - Received heartbeat request from 5153e4ff24b25b13225f1bf67a4312d8.19:53:41.802 [flink-akka.actor.default-dispatcher-9] DEBUG org.apache.flink.runtime.jobmaster.JobMaster - Received heartbeat from 7d6ef313-3f78-4cee-bbb1-e234dcac6d30.19:53:42.988 [pool-3-thread-1] DEBUG org.apache.iotdb.flink.IoTDBSink - send event successfully19:53:42.988 [pool-6-thread-1] DEBUG org.apache.iotdb.flink.IoTDBSink - send event successfully19:53:42.990 [pool-4-thread-1] DEBUG org.apache.iotdb.flink.IoTDBSink - send event successfully19:53:45.990 [pool-7-thread-1] DEBUG org.apache.iotdb.flink.IoTDBSink - send event successfully19:53:45.992 [pool-9-thread-1] DEBUG org.apache.iotdb.flink.IoTDBSink - send event successfully19:53:45.994 [pool-5-thread-1] DEBUG org.apache.iotdb.flink.IoTDBSink - send event successfully IoTDB Kafka样例程序运行结果如下所示： Producer.java ...[2022-01-15 15:12:34,221] INFO New Producer: start. (com.huawei.bigdata.iotdb.Producer)[2022-01-15 15:12:39,369] INFO [Producer clientId=DemoProducer] Cluster ID: uDtuaWS_QUK02EtuZQ4Xew (org.apache.kafka.clients.Metadata)[2022-01-15 15:12:57,077] INFO The Producer have send 100 messages. (com.huawei.bigdata.iotdb.Producer)[2022-01-15 15:13:04,691] INFO The Producer have send 200 messages. (com.huawei.bigdata.iotdb.Producer)[2022-01-15 15:13:11,355] INFO The Producer have send 300 messages. (com.huawei.bigdata.iotdb.Producer)[2022-01-15 15:13:17,758] INFO The Producer have send 400 messages. (com.huawei.bigdata.iotdb.Producer)[2022-01-15 15:13:24,335] INFO The Producer have send 500 messages. (com.huawei.bigdata.iotdb.Producer)[2022-01-15 15:13:30,739] INFO The Producer have send 600 messages. (com.huawei.bigdata.iotdb.Producer)[2022-01-15 15:13:37,267] INFO The Producer have send 700 messages. (com.huawei.bigdata.iotdb.Producer) KafkaConsumerMultThread.java ...[2022-01-15 15:19:27,563] INFO Consumer Thread-1 partitions:1 record: sensor_29,1642231023769,1.000000 offsets: 828 (com.huawei.bigdata.iotdb.KafkaConsumerMultThread)[2022-01-15 15:19:27,612] INFO Consumer Thread-1 partitions:1 record: sensor_31,1642231023769,1.000000 offsets: 829 (com.huawei.bigdata.iotdb.KafkaConsumerMultThread)[2022-01-15 15:19:27,612] INFO Consumer Thread-0 partitions:0 record: sensor_8,1642231023769,1.000000 offsets: 842 (com.huawei.bigdata.iotdb.KafkaConsumerMultThread)[2022-01-15 15:19:27,665] INFO Consumer Thread-1 partitions:1 record: sensor_32,1642231023769,1.000000 offsets: 830 (com.huawei.bigdata.iotdb.KafkaConsumerMultThread)[2022-01-15 15:19:27,665] INFO Consumer Thread-0 partitions:0 record: sensor_9,1642231023769,1.000000 offsets: 843 (com.huawei.bigdata.iotdb.KafkaConsumerMultThread)[2022-01-15 15:19:27,732] INFO Consumer Thread-1 partitions:1 record: sensor_33,1642231023769,1.000000 offsets: 831 (com.huawei.bigdata.iotdb.KafkaConsumerMultThread)[2022-01-15 15:19:27,732] INFO Consumer Thread-0 partitions:0 record: sensor_11,1642231023769,1.000000 offsets: 844 (com.huawei.bigdata.iotdb.KafkaConsumerMultThread)[2022-01-15 15:19:27,786] INFO Consumer Thread-0 partitions:0 record: sensor_12,1642231023769,1.000000 offsets: 845 (com.huawei.bigdata.iotdb.KafkaConsumerMultThread)[2022-01-15 15:19:27,786] INFO Consumer Thread-1 partitions:1 record: sensor_35,1642231023769,1.000000 offsets: 832 (com.huawei.bigdata.iotdb.KafkaConsumerMultThread)

IoTDB应用开发流程介绍 本文档主要基于Java API对IoTDB进行应用开发。 开发流程中各阶段的说明如图1和表1所示。 图1 IoTDB应用程序开发流程 表1 IoTDB应用开发的流程说明 阶段 说明 参考章节 准备开发环境 在进行应用开发前，需首先准备开发环境，推荐使用Java语言进行开发，使用IntelliJ IDEA工具，同时完成JDK、Maven等初始配置。 准备本地应用开发环境 准备连接集群配置文件 应用程序开发或运行过程中，需通过集群相关配置文件信息连接 MRS 集群，配置文件通常包括集群组件信息文件以及用于安全认证的用户文件，可从已创建好的MRS集群中获取相关内容。 用于程序调测或运行的节点，需要与MRS集群内节点网络互通，同时配置hosts 域名 信息。 准备连接IoTDB集群配置文件 配置并导入样例工程 IoTDB提供了不同场景下的多种样例程序，用户可获取样例工程并导入本地开发环境中进行程序学习。 导入并配置IoTDB样例工程 根据业务场景开发程序 提供了Java语言的样例工程，包含JDBC和Session两种连接方式，从创建存储组、创建时间序列，到插入数据再到删除存储组全流程的样例工程。 开发IoTDB应用 编译并运行程序 指导用户将开发好的程序编译并提交运行。 调测IoTDB应用 父主题： IoTDB开发指南（安全模式）

IoTDB应用开发流程介绍 本文档主要基于Java API对IoTDB进行应用开发。 开发流程中各阶段的说明如图1和表1所示。 图1 IoTDB应用程序开发流程 表1 IoTDB应用开发的流程说明 阶段 说明 参考文档 准备开发环境 在进行应用开发前，需首先准备开发环境，推荐使用Java语言进行开发，使用IntelliJ IDEA工具，同时完成JDK、Maven等初始配置。 准备本地应用开发环境 准备连接集群配置文件 应用程序开发或运行过程中，需通过集群相关配置文件信息连接MRS集群，配置文件通常包括集群组件信息文件以及用于安全认证的用户文件，可从已创建好的MRS集群中获取相关内容。 用于程序调测或运行的节点，需要与MRS集群内节点网络互通，同时配置hosts域名信息。 准备连接IoTDB集群配置文件 准备工程 IoTDB提供了不同场景下的多种样例程序，用户可获取样例工程并导入本地开发环境中进行程序学习。 导入并配置IoTDB样例工程 根据业务场景开发程序 提供了Java语言的样例工程，包含JDBC和Session两种连接方式，从创建存储组、创建时间序列，到插入数据再到删除存储组全流程的样例工程。 开发IoTDB应用 编译并运行程序 指导用户将开发好的程序编译并提交运行。 调测IoTDB应用 父主题： IoTDB开发指南（普通模式）

生成IoTDB客户端SSL证书 若集群开启了SSL加密传输且本地Windows或Linux环境首次运行IoTDB样例代码，需执行以下操作生成客户端SSL证书。 以客户端安装用户，登录安装客户端的节点。 切换到IoTDB客户端安装目录，例如：/opt/client。 cd /opt/client 执行以下命令配置环境变量。 source bigdata_env 执行以下命令生成客户端SSL证书“truststore.jks”： keytool -noprompt -import -alias myservercert -file ca.crt -keystore truststore.jks 执行该命令后需输入一个自定义密码。 若需在Linux环境中运行样例代码，需将生成的“truststore.jks”文件复制到“客户端安装目录/IoTDB/iotdb/conf”目录下： cp truststore.jks 客户端安装目录/IoTDB/iotdb/conf

代码样例 以下为代码片段示例： package com.huawei.bigdata.iotdb;import org.apache.iotdb.udf.api.UDTF;import org.apache.iotdb.udf.api.access.Row;import org.apache.iotdb.udf.api.collector.PointCollector;import org.apache.iotdb.udf.api.customizer.config.UDTFConfigurations;import org.apache.iotdb.udf.api.customizer.parameter.UDFParameters;import org.apache.iotdb.udf.api.customizer.strategy.RowByRowAccessStrategy;import org.apache.iotdb.udf.api.type.Type;import java.io.IOException;public class UDTFExample implements UDTF { @Override public void beforeStart(UDFParameters parameters, UDTFConfigurations configurations) { configurations.setAccessStrategy(new RowByRowAccessStrategy()).setOutputDataType(Type.INT32); } @Override public void transform(Row row, PointCollector collector) throws IOException { collector.putInt(row.getTime(), -row.getInt(0)); }}