import{_ as i,r as o,o as l,c as r,a as p,d as a,e as n,b as s,w as u,f as t}from"./app-ef44ea71.js";const d={},k=t('<h1 id="user-defined-function-udf" tabindex="-1"><a class="header-anchor" href="#user-defined-function-udf" aria-hidden="true">#</a> User Defined Function (UDF)</h1><p>IoTDB provides a variety of built-in functions to meet your computing needs, and you can also create user defined functions to meet more computing needs.</p><p>This document describes how to write, register and use a UDF.</p><h2 id="udf-types" tabindex="-1"><a class="header-anchor" href="#udf-types" aria-hidden="true">#</a> UDF Types</h2><p>In IoTDB, you can expand two types of UDF:</p><table><thead><tr><th>UDF Class</th><th>Description</th></tr></thead><tbody><tr><td>UDTF（User Defined Timeseries Generating Function）</td><td>This type of function can take <strong>multiple</strong> time series as input, and output <strong>one</strong> time series, which can have any number of data points.</td></tr><tr><td>UDAF（User Defined Aggregation Function）</td><td>Under development, please stay tuned.</td></tr></tbody></table><h2 id="udf-development-dependencies" tabindex="-1"><a class="header-anchor" href="#udf-development-dependencies" aria-hidden="true">#</a> UDF Development Dependencies</h2>',7),m={href:"http://search.maven.org/",target:"_blank",rel:"noopener noreferrer"},h={href:"http://search.maven.org/",target:"_blank",rel:"noopener noreferrer"},f=t(`<div class="language-xml line-numbers-mode" data-ext="xml"><pre class="language-xml"><code><span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>dependency</span><span class="token punctuation">&gt;</span></span>
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>groupId</span><span class="token punctuation">&gt;</span></span>org.apache.iotdb<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>groupId</span><span class="token punctuation">&gt;</span></span>
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>artifactId</span><span class="token punctuation">&gt;</span></span>iotdb-server<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>artifactId</span><span class="token punctuation">&gt;</span></span>
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>version</span><span class="token punctuation">&gt;</span></span>0.13.0-SNAPSHOT<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>version</span><span class="token punctuation">&gt;</span></span>
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>scope</span><span class="token punctuation">&gt;</span></span>provided<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>scope</span><span class="token punctuation">&gt;</span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>dependency</span><span class="token punctuation">&gt;</span></span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h2 id="udtf-user-defined-timeseries-generating-function" tabindex="-1"><a class="header-anchor" href="#udtf-user-defined-timeseries-generating-function" aria-hidden="true">#</a> UDTF（User Defined Timeseries Generating Function）</h2><p>To write a UDTF, you need to inherit the <code>org.apache.iotdb.db.query.udf.api.UDTF</code> class, and at least implement the <code>beforeStart</code> method and a <code>transform</code> method.</p><p>The following table shows all the interfaces available for user implementation.</p><table><thead><tr><th style="text-align:left;">Interface definition</th><th style="text-align:left;">Description</th><th>Required to Implement</th></tr></thead><tbody><tr><td style="text-align:left;"><code>void validate(UDFParameterValidator validator) throws Exception</code></td><td style="text-align:left;">This method is mainly used to validate <code>UDFParameters</code> and it is executed before <code>beforeStart(UDFParameters, UDTFConfigurations)</code> is called.</td><td>Optional</td></tr><tr><td style="text-align:left;"><code>void beforeStart(UDFParameters parameters, UDTFConfigurations configurations) throws Exception</code></td><td style="text-align:left;">The initialization method to call the user-defined initialization behavior before a UDTF processes the input data. Every time a user executes a UDTF query, the framework will construct a new UDF instance, and <code>beforeStart</code> will be called.</td><td>Required</td></tr><tr><td style="text-align:left;"><code>void transform(Row row, PointCollector collector) throws Exception</code></td><td style="text-align:left;">This method is called by the framework. This data processing method will be called when you choose to use the <code>RowByRowAccessStrategy</code> strategy (set in <code>beforeStart</code>) to consume raw data. Input data is passed in by <code>Row</code>, and the transformation result should be output by <code>PointCollector</code>. You need to call the data collection method provided by <code>collector</code> to determine the output data.</td><td>Required to implement at least one <code>transform</code> method</td></tr><tr><td style="text-align:left;"><code>void transform(RowWindow rowWindow, PointCollector collector) throws Exception</code></td><td style="text-align:left;">This method is called by the framework. This data processing method will be called when you choose to use the <code>SlidingSizeWindowAccessStrategy</code> or <code>SlidingTimeWindowAccessStrategy</code> strategy (set in <code>beforeStart</code>) to consume raw data. Input data is passed in by <code>RowWindow</code>, and the transformation result should be output by <code>PointCollector</code>. You need to call the data collection method provided by <code>collector</code> to determine the output data.</td><td>Required to implement at least one <code>transform</code> method</td></tr><tr><td style="text-align:left;"><code>void terminate(PointCollector collector) throws Exception</code></td><td style="text-align:left;">This method is called by the framework. This method will be called once after all <code>transform</code> calls have been executed. In a single UDF query, this method will and will only be called once. You need to call the data collection method provided by <code>collector</code> to determine the output data.</td><td>Optional</td></tr><tr><td style="text-align:left;"><code>void beforeDestroy() </code></td><td style="text-align:left;">This method is called by the framework after the last input data is processed, and will only be called once in the life cycle of each UDF instance.</td><td>Optional</td></tr></tbody></table><p>In the life cycle of a UDTF instance, the calling sequence of each method is as follows:</p><ol><li><code>void validate(UDFParameterValidator validator) throws Exception</code></li><li><code>void beforeStart(UDFParameters parameters, UDTFConfigurations configurations) throws Exception</code></li><li><code>void transform(Row row, PointCollector collector) throws Exception</code> or <code>void transform(RowWindow rowWindow, PointCollector collector) throws Exception</code></li><li><code>void terminate(PointCollector collector) throws Exception</code></li><li><code>void beforeDestroy() </code></li></ol><p>Note that every time the framework executes a UDTF query, a new UDF instance will be constructed. When the query ends, the corresponding instance will be destroyed. Therefore, the internal data of the instances in different UDTF queries (even in the same SQL statement) are isolated. You can maintain some state data in the UDTF without considering the influence of concurrency and other factors.</p><p>The usage of each interface will be described in detail below.</p><h3 id="void-validate-udfparametervalidator-validator-throws-exception" tabindex="-1"><a class="header-anchor" href="#void-validate-udfparametervalidator-validator-throws-exception" aria-hidden="true">#</a> void validate(UDFParameterValidator validator) throws Exception</h3><p>The <code>validate</code> method is used to validate the parameters entered by the user.</p><p>In this method, you can limit the number and types of input time series, check the attributes of user input, or perform any custom verification.</p><p>Please refer to the Javadoc for the usage of <code>UDFParameterValidator</code>.</p><h3 id="void-beforestart-udfparameters-parameters-udtfconfigurations-configurations-throws-exception" tabindex="-1"><a class="header-anchor" href="#void-beforestart-udfparameters-parameters-udtfconfigurations-configurations-throws-exception" aria-hidden="true">#</a> void beforeStart(UDFParameters parameters, UDTFConfigurations configurations) throws Exception</h3><p>This method is mainly used to customize UDTF. In this method, the user can do the following things:</p><ol><li>Use UDFParameters to get the time series paths and parse key-value pair attributes entered by the user.</li><li>Set the strategy to access the raw data and set the output data type in UDTFConfigurations.</li><li>Create resources, such as establishing external connections, opening files, etc.</li></ol><h4 id="udfparameters" tabindex="-1"><a class="header-anchor" href="#udfparameters" aria-hidden="true">#</a> UDFParameters</h4><p><code>UDFParameters</code> is used to parse UDF parameters in SQL statements (the part in parentheses after the UDF function name in SQL). The input parameters have two parts. The first part is the paths (measurements) and their data types of the time series that the UDF needs to process, and the second part is the key-value pair attributes for customization. Only the second part can be empty.</p><p>Example：</p><div class="language-sql line-numbers-mode" data-ext="sql"><pre class="language-sql"><code><span class="token keyword">SELECT</span> UDF<span class="token punctuation">(</span>s1<span class="token punctuation">,</span> s2<span class="token punctuation">,</span> <span class="token string">&#39;key1&#39;</span><span class="token operator">=</span><span class="token string">&#39;iotdb&#39;</span><span class="token punctuation">,</span> <span class="token string">&#39;key2&#39;</span><span class="token operator">=</span><span class="token string">&#39;123.45&#39;</span><span class="token punctuation">)</span> <span class="token keyword">FROM</span> root<span class="token punctuation">.</span>sg<span class="token punctuation">.</span>d<span class="token punctuation">;</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><p>Usage：</p><div class="language-java line-numbers-mode" data-ext="java"><pre class="language-java"><code><span class="token keyword">void</span> <span class="token function">beforeStart</span><span class="token punctuation">(</span><span class="token class-name">UDFParameters</span> parameters<span class="token punctuation">,</span> <span class="token class-name">UDTFConfigurations</span> configurations<span class="token punctuation">)</span> <span class="token keyword">throws</span> <span class="token class-name">Exception</span> <span class="token punctuation">{</span>
  <span class="token comment">// parameters</span>
	<span class="token keyword">for</span> <span class="token punctuation">(</span><span class="token class-name">PartialPath</span> path <span class="token operator">:</span> parameters<span class="token punctuation">.</span><span class="token function">getPaths</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
    <span class="token class-name">TSDataType</span> dataType <span class="token operator">=</span> parameters<span class="token punctuation">.</span><span class="token function">getDataType</span><span class="token punctuation">(</span>path<span class="token punctuation">)</span><span class="token punctuation">;</span>
  	<span class="token comment">// do something</span>
  <span class="token punctuation">}</span>
  <span class="token class-name">String</span> stringValue <span class="token operator">=</span> parameters<span class="token punctuation">.</span><span class="token function">getString</span><span class="token punctuation">(</span><span class="token string">&quot;key1&quot;</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// iotdb</span>
  <span class="token class-name">Float</span> floatValue <span class="token operator">=</span> parameters<span class="token punctuation">.</span><span class="token function">getFloat</span><span class="token punctuation">(</span><span class="token string">&quot;key2&quot;</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// 123.45</span>
  <span class="token class-name">Double</span> doubleValue <span class="token operator">=</span> parameters<span class="token punctuation">.</span><span class="token function">getDouble</span><span class="token punctuation">(</span><span class="token string">&quot;key3&quot;</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// null</span>
  <span class="token keyword">int</span> intValue <span class="token operator">=</span> parameters<span class="token punctuation">.</span><span class="token function">getIntOrDefault</span><span class="token punctuation">(</span><span class="token string">&quot;key4&quot;</span><span class="token punctuation">,</span> <span class="token number">678</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// 678</span>
  <span class="token comment">// do something</span>
  
  <span class="token comment">// configurations</span>
  <span class="token comment">// ...</span>
<span class="token punctuation">}</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h4 id="udtfconfigurations" tabindex="-1"><a class="header-anchor" href="#udtfconfigurations" aria-hidden="true">#</a> UDTFConfigurations</h4><p>You must use <code>UDTFConfigurations</code> to specify the strategy used by UDF to access raw data and the type of output sequence.</p><p>Usage：</p><div class="language-java line-numbers-mode" data-ext="java"><pre class="language-java"><code><span class="token keyword">void</span> <span class="token function">beforeStart</span><span class="token punctuation">(</span><span class="token class-name">UDFParameters</span> parameters<span class="token punctuation">,</span> <span class="token class-name">UDTFConfigurations</span> configurations<span class="token punctuation">)</span> <span class="token keyword">throws</span> <span class="token class-name">Exception</span> <span class="token punctuation">{</span>
  <span class="token comment">// parameters</span>
  <span class="token comment">// ...</span>
  
  <span class="token comment">// configurations</span>
  configurations
    <span class="token punctuation">.</span><span class="token function">setAccessStrategy</span><span class="token punctuation">(</span><span class="token keyword">new</span> <span class="token class-name">RowByRowAccessStrategy</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
    <span class="token punctuation">.</span><span class="token function">setOutputDataType</span><span class="token punctuation">(</span><span class="token class-name">TSDataType</span><span class="token punctuation">.</span><span class="token constant">INT32</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>The <code>setAccessStrategy</code> method is used to set the UDF&#39;s strategy for accessing the raw data, and the <code>setOutputDataType</code> method is used to set the data type of the output sequence.</p><h5 id="setaccessstrategy" tabindex="-1"><a class="header-anchor" href="#setaccessstrategy" aria-hidden="true">#</a> setAccessStrategy</h5><p>Note that the raw data access strategy you set here determines which <code>transform</code> method the framework will call. Please implement the <code>transform</code> method corresponding to the raw data access strategy. Of course, you can also dynamically decide which strategy to set based on the attribute parameters parsed by <code>UDFParameters</code>. Therefore, two <code>transform</code> methods are also allowed to be implemented in one UDF.</p><p>The following are the strategies you can set:</p><table><thead><tr><th style="text-align:left;">Interface definition</th><th style="text-align:left;">Description</th><th>The <code>transform</code> Method to Call</th></tr></thead><tbody><tr><td style="text-align:left;"><code>RowByRowAccessStrategy</code></td><td style="text-align:left;">Process raw data row by row. The framework calls the <code>transform</code> method once for each row of raw data input. When UDF has only one input sequence, a row of input is one data point in the input sequence. When UDF has multiple input sequences, one row of input is a result record of the raw query (aligned by time) on these input sequences. (In a row, there may be a column with a value of <code>null</code>, but not all of them are <code>null</code>)</td><td><code>void transform(Row row, PointCollector collector) throws Exception</code></td></tr><tr><td style="text-align:left;"><code>SlidingTimeWindowAccessStrategy</code></td><td style="text-align:left;">Process a batch of data in a fixed time interval each time. We call the container of a data batch a window. The framework calls the <code>transform</code> method once for each raw data input window. There may be multiple rows of data in a window, and each row is a result record of the raw query (aligned by time) on these input sequences. (In a row, there may be a column with a value of <code>null</code>, but not all of them are <code>null</code>)</td><td><code>void transform(RowWindow rowWindow, PointCollector collector) throws Exception</code></td></tr><tr><td style="text-align:left;"><code>SlidingSizeWindowAccessStrategy</code></td><td style="text-align:left;">The raw data is processed batch by batch, and each batch contains a fixed number of raw data rows (except the last batch). We call the container of a data batch a window. The framework calls the <code>transform</code> method once for each raw data input window. There may be multiple rows of data in a window, and each row is a result record of the raw query (aligned by time) on these input sequences. (In a row, there may be a column with a value of <code>null</code>, but not all of them are <code>null</code>)</td><td><code>void transform(RowWindow rowWindow, PointCollector collector) throws Exception</code></td></tr></tbody></table><p><code>RowByRowAccessStrategy</code>: The construction of <code>RowByRowAccessStrategy</code> does not require any parameters.</p><p><code>SlidingTimeWindowAccessStrategy</code>: <code>SlidingTimeWindowAccessStrategy</code> has many constructors, you can pass 3 types of parameters to them:</p><ul><li>Parameter 1: The display window on the time axis</li><li>Parameter 2: Time interval for dividing the time axis (should be positive)</li><li>Parameter 3: Time sliding step (not required to be greater than or equal to the time interval, but must be a positive number)</li></ul><p>The first type of parameters are optional. If the parameters are not provided, the beginning time of the display window will be set to the same as the minimum timestamp of the query result set, and the ending time of the display window will be set to the same as the maximum timestamp of the query result set.</p><p>The sliding step parameter is also optional. If the parameter is not provided, the sliding step will be set to the same as the time interval for dividing the time axis.</p><p>The relationship between the three types of parameters can be seen in the figure below. Please see the Javadoc for more details.</p><div style="text-align:center;"><img style="width:100%;max-width:800px;max-height:600px;margin-left:auto;margin-right:auto;display:block;" src="https://alioss.timecho.com/docs/img/github/99787878-47b51480-2b5b-11eb-8ed3-84088c5c30f7.png"></div><p>Note that the actual time interval of some of the last time windows may be less than the specified time interval parameter. In addition, there may be cases where the number of data rows in some time windows is 0. In these cases, the framework will also call the <code>transform</code> method for the empty windows.</p><p><code>SlidingSizeWindowAccessStrategy</code>: <code>SlidingSizeWindowAccessStrategy</code> has many constructors, you can pass 2 types of parameters to them:</p><ul><li>Parameter 1: Window size. This parameter specifies the number of data rows contained in a data processing window. Note that the number of data rows in some of the last time windows may be less than the specified number of data rows.</li><li>Parameter 2: Sliding step. This parameter means the number of rows between the first point of the next window and the first point of the current window. (This parameter is not required to be greater than or equal to the window size, but must be a positive number)</li></ul><p>The sliding step parameter is optional. If the parameter is not provided, the sliding step will be set to the same as the window size.</p><p>Please see the Javadoc for more details.</p><h5 id="setoutputdatatype" tabindex="-1"><a class="header-anchor" href="#setoutputdatatype" aria-hidden="true">#</a> setOutputDataType</h5><p>Note that the type of output sequence you set here determines the type of data that the <code>PointCollector</code> can actually receive in the <code>transform</code> method. The relationship between the output data type set in <code>setOutputDataType</code> and the actual data output type that <code>PointCollector</code> can receive is as follows:</p><table><thead><tr><th style="text-align:left;">Output Data Type Set in <code>setOutputDataType</code></th><th style="text-align:left;">Data Type that <code>PointCollector</code> Can Receive</th></tr></thead><tbody><tr><td style="text-align:left;"><code>INT32</code></td><td style="text-align:left;"><code>int</code></td></tr><tr><td style="text-align:left;"><code>INT64</code></td><td style="text-align:left;"><code>long</code></td></tr><tr><td style="text-align:left;"><code>FLOAT</code></td><td style="text-align:left;"><code>float</code></td></tr><tr><td style="text-align:left;"><code>DOUBLE</code></td><td style="text-align:left;"><code>double</code></td></tr><tr><td style="text-align:left;"><code>BOOLEAN</code></td><td style="text-align:left;"><code>boolean</code></td></tr><tr><td style="text-align:left;"><code>TEXT</code></td><td style="text-align:left;"><code>java.lang.String</code> and <code>org.apache.iotdb.tsfile.utils.Binary</code></td></tr></tbody></table><p>The type of output time series of a UDTF is determined at runtime, which means that a UDTF can dynamically determine the type of output time series according to the type of input time series.<br> Here is a simple example:</p><div class="language-java line-numbers-mode" data-ext="java"><pre class="language-java"><code><span class="token keyword">void</span> <span class="token function">beforeStart</span><span class="token punctuation">(</span><span class="token class-name">UDFParameters</span> parameters<span class="token punctuation">,</span> <span class="token class-name">UDTFConfigurations</span> configurations<span class="token punctuation">)</span> <span class="token keyword">throws</span> <span class="token class-name">Exception</span> <span class="token punctuation">{</span>
  <span class="token comment">// do something</span>
  <span class="token comment">// ...</span>
  
  configurations
    <span class="token punctuation">.</span><span class="token function">setAccessStrategy</span><span class="token punctuation">(</span><span class="token keyword">new</span> <span class="token class-name">RowByRowAccessStrategy</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
    <span class="token punctuation">.</span><span class="token function">setOutputDataType</span><span class="token punctuation">(</span>parameters<span class="token punctuation">.</span><span class="token function">getDataType</span><span class="token punctuation">(</span><span class="token number">0</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h3 id="void-transform-row-row-pointcollector-collector-throws-exception" tabindex="-1"><a class="header-anchor" href="#void-transform-row-row-pointcollector-collector-throws-exception" aria-hidden="true">#</a> void transform(Row row, PointCollector collector) throws Exception</h3><p>You need to implement this method when you specify the strategy of UDF to read the original data as <code>RowByRowAccessStrategy</code>.</p><p>This method processes the raw data one row at a time. The raw data is input from <code>Row</code> and output by <code>PointCollector</code>. You can output any number of data points in one <code>transform</code> method call. It should be noted that the type of output data points must be the same as you set in the <code>beforeStart</code> method, and the timestamps of output data points must be strictly monotonically increasing.</p><p>The following is a complete UDF example that implements the <code>void transform(Row row, PointCollector collector) throws Exception</code> method. It is an adder that receives two columns of time series as input. When two data points in a row are not <code>null</code>, this UDF will output the algebraic sum of these two data points.</p><div class="language-java line-numbers-mode" data-ext="java"><pre class="language-java"><code><span class="token keyword">import</span> <span class="token import"><span class="token namespace">org<span class="token punctuation">.</span>apache<span class="token punctuation">.</span>iotdb<span class="token punctuation">.</span>db<span class="token punctuation">.</span>query<span class="token punctuation">.</span>udf<span class="token punctuation">.</span>api<span class="token punctuation">.</span></span><span class="token class-name">UDTF</span></span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token import"><span class="token namespace">org<span class="token punctuation">.</span>apache<span class="token punctuation">.</span>iotdb<span class="token punctuation">.</span>db<span class="token punctuation">.</span>query<span class="token punctuation">.</span>udf<span class="token punctuation">.</span>api<span class="token punctuation">.</span>access<span class="token punctuation">.</span></span><span class="token class-name">Row</span></span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token import"><span class="token namespace">org<span class="token punctuation">.</span>apache<span class="token punctuation">.</span>iotdb<span class="token punctuation">.</span>db<span class="token punctuation">.</span>query<span class="token punctuation">.</span>udf<span class="token punctuation">.</span>api<span class="token punctuation">.</span>collector<span class="token punctuation">.</span></span><span class="token class-name">PointCollector</span></span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token import"><span class="token namespace">org<span class="token punctuation">.</span>apache<span class="token punctuation">.</span>iotdb<span class="token punctuation">.</span>db<span class="token punctuation">.</span>query<span class="token punctuation">.</span>udf<span class="token punctuation">.</span>api<span class="token punctuation">.</span>customizer<span class="token punctuation">.</span>config<span class="token punctuation">.</span></span><span class="token class-name">UDTFConfigurations</span></span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token import"><span class="token namespace">org<span class="token punctuation">.</span>apache<span class="token punctuation">.</span>iotdb<span class="token punctuation">.</span>db<span class="token punctuation">.</span>query<span class="token punctuation">.</span>udf<span class="token punctuation">.</span>api<span class="token punctuation">.</span>customizer<span class="token punctuation">.</span>parameter<span class="token punctuation">.</span></span><span class="token class-name">UDFParameters</span></span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token import"><span class="token namespace">org<span class="token punctuation">.</span>apache<span class="token punctuation">.</span>iotdb<span class="token punctuation">.</span>db<span class="token punctuation">.</span>query<span class="token punctuation">.</span>udf<span class="token punctuation">.</span>api<span class="token punctuation">.</span>customizer<span class="token punctuation">.</span>strategy<span class="token punctuation">.</span></span><span class="token class-name">RowByRowAccessStrategy</span></span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token import"><span class="token namespace">org<span class="token punctuation">.</span>apache<span class="token punctuation">.</span>iotdb<span class="token punctuation">.</span>tsfile<span class="token punctuation">.</span>file<span class="token punctuation">.</span>metadata<span class="token punctuation">.</span>enums<span class="token punctuation">.</span></span><span class="token class-name">TSDataType</span></span><span class="token punctuation">;</span>

<span class="token keyword">public</span> <span class="token keyword">class</span> <span class="token class-name">Adder</span> <span class="token keyword">implements</span> <span class="token class-name">UDTF</span> <span class="token punctuation">{</span>

  <span class="token annotation punctuation">@Override</span>
  <span class="token keyword">public</span> <span class="token keyword">void</span> <span class="token function">beforeStart</span><span class="token punctuation">(</span><span class="token class-name">UDFParameters</span> parameters<span class="token punctuation">,</span> <span class="token class-name">UDTFConfigurations</span> configurations<span class="token punctuation">)</span> <span class="token punctuation">{</span>
    configurations
        <span class="token punctuation">.</span><span class="token function">setOutputDataType</span><span class="token punctuation">(</span><span class="token class-name">TSDataType</span><span class="token punctuation">.</span><span class="token constant">INT64</span><span class="token punctuation">)</span>
        <span class="token punctuation">.</span><span class="token function">setAccessStrategy</span><span class="token punctuation">(</span><span class="token keyword">new</span> <span class="token class-name">RowByRowAccessStrategy</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
  <span class="token punctuation">}</span>

  <span class="token annotation punctuation">@Override</span>
  <span class="token keyword">public</span> <span class="token keyword">void</span> <span class="token function">transform</span><span class="token punctuation">(</span><span class="token class-name">Row</span> row<span class="token punctuation">,</span> <span class="token class-name">PointCollector</span> collector<span class="token punctuation">)</span> <span class="token keyword">throws</span> <span class="token class-name">Exception</span> <span class="token punctuation">{</span>
    <span class="token keyword">if</span> <span class="token punctuation">(</span>row<span class="token punctuation">.</span><span class="token function">isNull</span><span class="token punctuation">(</span><span class="token number">0</span><span class="token punctuation">)</span> <span class="token operator">||</span> row<span class="token punctuation">.</span><span class="token function">isNull</span><span class="token punctuation">(</span><span class="token number">1</span><span class="token punctuation">)</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
      <span class="token keyword">return</span><span class="token punctuation">;</span>
    <span class="token punctuation">}</span>
    collector<span class="token punctuation">.</span><span class="token function">putLong</span><span class="token punctuation">(</span>row<span class="token punctuation">.</span><span class="token function">getTime</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">,</span> row<span class="token punctuation">.</span><span class="token function">getLong</span><span class="token punctuation">(</span><span class="token number">0</span><span class="token punctuation">)</span> <span class="token operator">+</span> row<span class="token punctuation">.</span><span class="token function">getLong</span><span class="token punctuation">(</span><span class="token number">1</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
  <span class="token punctuation">}</span>
<span class="token punctuation">}</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h3 id="void-transform-rowwindow-rowwindow-pointcollector-collector-throws-exception" tabindex="-1"><a class="header-anchor" href="#void-transform-rowwindow-rowwindow-pointcollector-collector-throws-exception" aria-hidden="true">#</a> void transform(RowWindow rowWindow, PointCollector collector) throws Exception</h3><p>You need to implement this method when you specify the strategy of UDF to read the original data as <code>SlidingTimeWindowAccessStrategy</code> or <code>SlidingSizeWindowAccessStrategy</code>.</p><p>This method processes a batch of data in a fixed number of rows or a fixed time interval each time, and we call the container containing this batch of data a window. The raw data is input from <code>RowWindow</code> and output by <code>PointCollector</code>. <code>RowWindow</code> can help you access a batch of <code>Row</code>, it provides a set of interfaces for random access and iterative access to this batch of <code>Row</code>. You can output any number of data points in one <code>transform</code> method call. It should be noted that the type of output data points must be the same as you set in the <code>beforeStart</code> method, and the timestamps of output data points must be strictly monotonically increasing.</p><p>Below is a complete UDF example that implements the <code>void transform(RowWindow rowWindow, PointCollector collector) throws Exception</code> method. It is a counter that receives any number of time series as input, and its function is to count and output the number of data rows in each time window within a specified time range.</p><div class="language-java line-numbers-mode" data-ext="java"><pre class="language-java"><code><span class="token keyword">import</span> <span class="token import"><span class="token namespace">java<span class="token punctuation">.</span>io<span class="token punctuation">.</span></span><span class="token class-name">IOException</span></span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token import"><span class="token namespace">org<span class="token punctuation">.</span>apache<span class="token punctuation">.</span>iotdb<span class="token punctuation">.</span>db<span class="token punctuation">.</span>query<span class="token punctuation">.</span>udf<span class="token punctuation">.</span>api<span class="token punctuation">.</span></span><span class="token class-name">UDTF</span></span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token import"><span class="token namespace">org<span class="token punctuation">.</span>apache<span class="token punctuation">.</span>iotdb<span class="token punctuation">.</span>db<span class="token punctuation">.</span>query<span class="token punctuation">.</span>udf<span class="token punctuation">.</span>api<span class="token punctuation">.</span>access<span class="token punctuation">.</span></span><span class="token class-name">RowWindow</span></span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token import"><span class="token namespace">org<span class="token punctuation">.</span>apache<span class="token punctuation">.</span>iotdb<span class="token punctuation">.</span>db<span class="token punctuation">.</span>query<span class="token punctuation">.</span>udf<span class="token punctuation">.</span>api<span class="token punctuation">.</span>collector<span class="token punctuation">.</span></span><span class="token class-name">PointCollector</span></span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token import"><span class="token namespace">org<span class="token punctuation">.</span>apache<span class="token punctuation">.</span>iotdb<span class="token punctuation">.</span>db<span class="token punctuation">.</span>query<span class="token punctuation">.</span>udf<span class="token punctuation">.</span>api<span class="token punctuation">.</span>customizer<span class="token punctuation">.</span>config<span class="token punctuation">.</span></span><span class="token class-name">UDTFConfigurations</span></span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token import"><span class="token namespace">org<span class="token punctuation">.</span>apache<span class="token punctuation">.</span>iotdb<span class="token punctuation">.</span>db<span class="token punctuation">.</span>query<span class="token punctuation">.</span>udf<span class="token punctuation">.</span>api<span class="token punctuation">.</span>customizer<span class="token punctuation">.</span>parameter<span class="token punctuation">.</span></span><span class="token class-name">UDFParameters</span></span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token import"><span class="token namespace">org<span class="token punctuation">.</span>apache<span class="token punctuation">.</span>iotdb<span class="token punctuation">.</span>db<span class="token punctuation">.</span>query<span class="token punctuation">.</span>udf<span class="token punctuation">.</span>api<span class="token punctuation">.</span>customizer<span class="token punctuation">.</span>strategy<span class="token punctuation">.</span></span><span class="token class-name">SlidingTimeWindowAccessStrategy</span></span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token import"><span class="token namespace">org<span class="token punctuation">.</span>apache<span class="token punctuation">.</span>iotdb<span class="token punctuation">.</span>tsfile<span class="token punctuation">.</span>file<span class="token punctuation">.</span>metadata<span class="token punctuation">.</span>enums<span class="token punctuation">.</span></span><span class="token class-name">TSDataType</span></span><span class="token punctuation">;</span>

<span class="token keyword">public</span> <span class="token keyword">class</span> <span class="token class-name">Counter</span> <span class="token keyword">implements</span> <span class="token class-name">UDTF</span> <span class="token punctuation">{</span>

  <span class="token annotation punctuation">@Override</span>
  <span class="token keyword">public</span> <span class="token keyword">void</span> <span class="token function">beforeStart</span><span class="token punctuation">(</span><span class="token class-name">UDFParameters</span> parameters<span class="token punctuation">,</span> <span class="token class-name">UDTFConfigurations</span> configurations<span class="token punctuation">)</span> <span class="token punctuation">{</span>
    configurations
        <span class="token punctuation">.</span><span class="token function">setOutputDataType</span><span class="token punctuation">(</span><span class="token class-name">TSDataType</span><span class="token punctuation">.</span><span class="token constant">INT32</span><span class="token punctuation">)</span>
        <span class="token punctuation">.</span><span class="token function">setAccessStrategy</span><span class="token punctuation">(</span><span class="token keyword">new</span> <span class="token class-name">SlidingTimeWindowAccessStrategy</span><span class="token punctuation">(</span>
            parameters<span class="token punctuation">.</span><span class="token function">getLong</span><span class="token punctuation">(</span><span class="token string">&quot;time_interval&quot;</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
            parameters<span class="token punctuation">.</span><span class="token function">getLong</span><span class="token punctuation">(</span><span class="token string">&quot;sliding_step&quot;</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
            parameters<span class="token punctuation">.</span><span class="token function">getLong</span><span class="token punctuation">(</span><span class="token string">&quot;display_window_begin&quot;</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
            parameters<span class="token punctuation">.</span><span class="token function">getLong</span><span class="token punctuation">(</span><span class="token string">&quot;display_window_end&quot;</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
  <span class="token punctuation">}</span>

  <span class="token annotation punctuation">@Override</span>
  <span class="token keyword">public</span> <span class="token keyword">void</span> <span class="token function">transform</span><span class="token punctuation">(</span><span class="token class-name">RowWindow</span> rowWindow<span class="token punctuation">,</span> <span class="token class-name">PointCollector</span> collector<span class="token punctuation">)</span> <span class="token punctuation">{</span>
    <span class="token keyword">if</span> <span class="token punctuation">(</span>rowWindow<span class="token punctuation">.</span><span class="token function">windowSize</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">!=</span> <span class="token number">0</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
      collector<span class="token punctuation">.</span><span class="token function">putInt</span><span class="token punctuation">(</span>rowWindow<span class="token punctuation">.</span><span class="token function">getRow</span><span class="token punctuation">(</span><span class="token number">0</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">getTime</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">,</span> rowWindow<span class="token punctuation">.</span><span class="token function">windowSize</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
    <span class="token punctuation">}</span>
  <span class="token punctuation">}</span>
<span class="token punctuation">}</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h3 id="void-terminate-pointcollector-collector-throws-exception" tabindex="-1"><a class="header-anchor" href="#void-terminate-pointcollector-collector-throws-exception" aria-hidden="true">#</a> void terminate(PointCollector collector) throws Exception</h3><p>In some scenarios, a UDF needs to traverse all the original data to calculate the final output data points. The <code>terminate</code> interface provides support for those scenarios.</p><p>This method is called after all <code>transform</code> calls are executed and before the <code>beforeDestory</code> method is executed. You can implement the <code>transform</code> method to perform pure data processing (without outputting any data points), and implement the <code>terminate</code> method to output the processing results.</p><p>The processing results need to be output by the <code>PointCollector</code>. You can output any number of data points in one <code>terminate</code> method call. It should be noted that the type of output data points must be the same as you set in the <code>beforeStart</code> method, and the timestamps of output data points must be strictly monotonically increasing.</p><p>Below is a complete UDF example that implements the <code>void terminate(PointCollector collector) throws Exception</code> method. It takes one time series whose data type is <code>INT32</code> as input, and outputs the maximum value point of the series.</p><div class="language-java line-numbers-mode" data-ext="java"><pre class="language-java"><code><span class="token keyword">import</span> <span class="token import"><span class="token namespace">java<span class="token punctuation">.</span>io<span class="token punctuation">.</span></span><span class="token class-name">IOException</span></span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token import"><span class="token namespace">org<span class="token punctuation">.</span>apache<span class="token punctuation">.</span>iotdb<span class="token punctuation">.</span>db<span class="token punctuation">.</span>query<span class="token punctuation">.</span>udf<span class="token punctuation">.</span>api<span class="token punctuation">.</span></span><span class="token class-name">UDTF</span></span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token import"><span class="token namespace">org<span class="token punctuation">.</span>apache<span class="token punctuation">.</span>iotdb<span class="token punctuation">.</span>db<span class="token punctuation">.</span>query<span class="token punctuation">.</span>udf<span class="token punctuation">.</span>api<span class="token punctuation">.</span>access<span class="token punctuation">.</span></span><span class="token class-name">Row</span></span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token import"><span class="token namespace">org<span class="token punctuation">.</span>apache<span class="token punctuation">.</span>iotdb<span class="token punctuation">.</span>db<span class="token punctuation">.</span>query<span class="token punctuation">.</span>udf<span class="token punctuation">.</span>api<span class="token punctuation">.</span>collector<span class="token punctuation">.</span></span><span class="token class-name">PointCollector</span></span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token import"><span class="token namespace">org<span class="token punctuation">.</span>apache<span class="token punctuation">.</span>iotdb<span class="token punctuation">.</span>db<span class="token punctuation">.</span>query<span class="token punctuation">.</span>udf<span class="token punctuation">.</span>api<span class="token punctuation">.</span>customizer<span class="token punctuation">.</span>config<span class="token punctuation">.</span></span><span class="token class-name">UDTFConfigurations</span></span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token import"><span class="token namespace">org<span class="token punctuation">.</span>apache<span class="token punctuation">.</span>iotdb<span class="token punctuation">.</span>db<span class="token punctuation">.</span>query<span class="token punctuation">.</span>udf<span class="token punctuation">.</span>api<span class="token punctuation">.</span>customizer<span class="token punctuation">.</span>parameter<span class="token punctuation">.</span></span><span class="token class-name">UDFParameters</span></span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token import"><span class="token namespace">org<span class="token punctuation">.</span>apache<span class="token punctuation">.</span>iotdb<span class="token punctuation">.</span>db<span class="token punctuation">.</span>query<span class="token punctuation">.</span>udf<span class="token punctuation">.</span>api<span class="token punctuation">.</span>customizer<span class="token punctuation">.</span>strategy<span class="token punctuation">.</span></span><span class="token class-name">RowByRowAccessStrategy</span></span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token import"><span class="token namespace">org<span class="token punctuation">.</span>apache<span class="token punctuation">.</span>iotdb<span class="token punctuation">.</span>tsfile<span class="token punctuation">.</span>file<span class="token punctuation">.</span>metadata<span class="token punctuation">.</span>enums<span class="token punctuation">.</span></span><span class="token class-name">TSDataType</span></span><span class="token punctuation">;</span>

<span class="token keyword">public</span> <span class="token keyword">class</span> <span class="token class-name">Max</span> <span class="token keyword">implements</span> <span class="token class-name">UDTF</span> <span class="token punctuation">{</span>

  <span class="token keyword">private</span> <span class="token class-name">Long</span> time<span class="token punctuation">;</span>
  <span class="token keyword">private</span> <span class="token keyword">int</span> value<span class="token punctuation">;</span>

  <span class="token annotation punctuation">@Override</span>
  <span class="token keyword">public</span> <span class="token keyword">void</span> <span class="token function">beforeStart</span><span class="token punctuation">(</span><span class="token class-name">UDFParameters</span> parameters<span class="token punctuation">,</span> <span class="token class-name">UDTFConfigurations</span> configurations<span class="token punctuation">)</span> <span class="token punctuation">{</span>
    configurations
        <span class="token punctuation">.</span><span class="token function">setOutputDataType</span><span class="token punctuation">(</span><span class="token class-name">TSDataType</span><span class="token punctuation">.</span><span class="token constant">INT32</span><span class="token punctuation">)</span>
        <span class="token punctuation">.</span><span class="token function">setAccessStrategy</span><span class="token punctuation">(</span><span class="token keyword">new</span> <span class="token class-name">RowByRowAccessStrategy</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
  <span class="token punctuation">}</span>

  <span class="token annotation punctuation">@Override</span>
  <span class="token keyword">public</span> <span class="token keyword">void</span> <span class="token function">transform</span><span class="token punctuation">(</span><span class="token class-name">Row</span> row<span class="token punctuation">,</span> <span class="token class-name">PointCollector</span> collector<span class="token punctuation">)</span> <span class="token punctuation">{</span>
    <span class="token keyword">int</span> candidateValue <span class="token operator">=</span> row<span class="token punctuation">.</span><span class="token function">getInt</span><span class="token punctuation">(</span><span class="token number">0</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
    <span class="token keyword">if</span> <span class="token punctuation">(</span>time <span class="token operator">==</span> <span class="token keyword">null</span> <span class="token operator">||</span> value <span class="token operator">&lt;</span> candidateValue<span class="token punctuation">)</span> <span class="token punctuation">{</span>
      time <span class="token operator">=</span> row<span class="token punctuation">.</span><span class="token function">getTime</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
      value <span class="token operator">=</span> candidateValue<span class="token punctuation">;</span>
    <span class="token punctuation">}</span>
  <span class="token punctuation">}</span>

  <span class="token annotation punctuation">@Override</span>
  <span class="token keyword">public</span> <span class="token keyword">void</span> <span class="token function">terminate</span><span class="token punctuation">(</span><span class="token class-name">PointCollector</span> collector<span class="token punctuation">)</span> <span class="token keyword">throws</span> <span class="token class-name">IOException</span> <span class="token punctuation">{</span>
    <span class="token keyword">if</span> <span class="token punctuation">(</span>time <span class="token operator">!=</span> <span class="token keyword">null</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
      collector<span class="token punctuation">.</span><span class="token function">putInt</span><span class="token punctuation">(</span>time<span class="token punctuation">,</span> value<span class="token punctuation">)</span><span class="token punctuation">;</span>
    <span class="token punctuation">}</span>
  <span class="token punctuation">}</span>
<span class="token punctuation">}</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h3 id="void-beforedestroy" tabindex="-1"><a class="header-anchor" href="#void-beforedestroy" aria-hidden="true">#</a> void beforeDestroy()</h3><p>The method for terminating a UDF.</p><p>This method is called by the framework. For a UDF instance, <code>beforeDestroy</code> will be called after the last record is processed. In the entire life cycle of the instance, <code>beforeDestroy</code> will only be called once.</p><h2 id="maven-project-example" tabindex="-1"><a class="header-anchor" href="#maven-project-example" aria-hidden="true">#</a> Maven Project Example</h2>`,68),b=a("strong",null,"udf-example",-1),v={href:"https://github.com/apache/iotdb/tree/master/example/udf",target:"_blank",rel:"noopener noreferrer"},g=t(`<h2 id="udf-registration" tabindex="-1"><a class="header-anchor" href="#udf-registration" aria-hidden="true">#</a> UDF Registration</h2><p>The process of registering a UDF in IoTDB is as follows:</p><ol><li><p>Implement a complete UDF class, assuming the full class name of this class is <code>org.apache.iotdb.udf.ExampleUDTF</code>.</p></li><li><p>Package your project into a JAR. If you use Maven to manage your project, you can refer to the Maven project example above.</p></li><li><p>Place the JAR package in the directory <code>iotdb-server-0.13.0-SNAPSHOT-all-bin/ext/udf</code> or in a subdirectory of <code>iotdb-server-0.13.0-SNAPSHOT-all-bin/ext/udf</code>.<br> **Note that when deploying a cluster, you need to ensure that there is a corresponding JAR package in the UDF JAR package path of each node. **</p><blockquote><p>You can specify the root path for the UDF to load the Jar by modifying the &#39;udf_root_dir&#39; in the configuration file.</p></blockquote></li><li><p>Register the UDF with the SQL statement, assuming that the name given to the UDF is <code>example</code>.</p></li></ol><p>The following shows the SQL syntax of how to register a UDF.</p><div class="language-sql line-numbers-mode" data-ext="sql"><pre class="language-sql"><code><span class="token keyword">CREATE</span> <span class="token keyword">FUNCTION</span> <span class="token operator">&lt;</span>UDF<span class="token operator">-</span>NAME<span class="token operator">&gt;</span> <span class="token keyword">AS</span> <span class="token operator">&lt;</span>UDF<span class="token operator">-</span>CLASS<span class="token operator">-</span><span class="token keyword">FULL</span><span class="token operator">-</span>PATHNAME<span class="token operator">&gt;</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><p>Here is an example:</p><div class="language-sql line-numbers-mode" data-ext="sql"><pre class="language-sql"><code><span class="token keyword">CREATE</span> <span class="token keyword">FUNCTION</span> example <span class="token keyword">AS</span> <span class="token string">&#39;org.apache.iotdb.udf.ExampleUDTF&#39;</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><p>Since UDF instances are dynamically loaded through reflection technology, you do not need to restart the server during the UDF registration process.</p><p>Note: UDF function names are not case sensitive.</p><p>Note: Please ensure that the function name given to the UDF is different from all built-in function names. A UDF with the same name as a built-in function cannot be registered.</p><p>Note: We recommend that you do not use classes that have the same class name but different function logic in different JAR packages. For example, in <code>UDF(UDAF/UDTF): udf1, udf2</code>, the JAR package of udf1 is <code>udf1.jar</code> and the JAR package of udf2 is <code>udf2.jar</code>. Assume that both JAR packages contain the <code>org.apache.iotdb.udf.ExampleUDTF</code> class. If you use two UDFs in the same SQL statement at the same time, the system will randomly load either of them and may cause inconsistency in UDF execution behavior.</p><h2 id="udf-deregistration" tabindex="-1"><a class="header-anchor" href="#udf-deregistration" aria-hidden="true">#</a> UDF Deregistration</h2><p>The following shows the SQL syntax of how to deregister a UDF.</p><div class="language-sql line-numbers-mode" data-ext="sql"><pre class="language-sql"><code><span class="token keyword">DROP</span> <span class="token keyword">FUNCTION</span> <span class="token operator">&lt;</span>UDF<span class="token operator">-</span>NAME<span class="token operator">&gt;</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><p>Here is an example:</p><div class="language-sql line-numbers-mode" data-ext="sql"><pre class="language-sql"><code><span class="token keyword">DROP</span> <span class="token keyword">FUNCTION</span> example
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><h2 id="udf-queries" tabindex="-1"><a class="header-anchor" href="#udf-queries" aria-hidden="true">#</a> UDF Queries</h2><p>The usage of UDF is similar to that of built-in aggregation functions.</p><h3 id="basic-sql-syntax-support" tabindex="-1"><a class="header-anchor" href="#basic-sql-syntax-support" aria-hidden="true">#</a> Basic SQL syntax support</h3><ul><li>Support <code>SLIMIT</code> / <code>SOFFSET</code></li><li>Support <code>LIMIT</code> / <code>OFFSET</code></li><li>Support <code>NON ALIGN</code></li><li>Support queries with time filters</li><li>Support queries with value filters</li></ul><h3 id="queries-with-aligned-timeseries" tabindex="-1"><a class="header-anchor" href="#queries-with-aligned-timeseries" aria-hidden="true">#</a> Queries with Aligned Timeseries</h3><p>Aligned Timeseries has not been supported in UDF queries yet. An error message is expected if you use UDF functions with Aligned Timeseries selected.</p><h3 id="queries-with-in-select-clauses" tabindex="-1"><a class="header-anchor" href="#queries-with-in-select-clauses" aria-hidden="true">#</a> Queries with * in SELECT Clauses</h3><p>Assume that there are 2 time series (<code>root.sg.d1.s1</code> and <code>root.sg.d1.s2</code>) in the system.</p><ul><li><strong><code>SELECT example(*) from root.sg.d1</code></strong></li></ul><p>Then the result set will include the results of <code>example (root.sg.d1.s1)</code> and <code>example (root.sg.d1.s2)</code>.</p><ul><li><strong><code>SELECT example(s1, *) from root.sg.d1</code></strong></li></ul><p>Then the result set will include the results of <code>example(root.sg.d1.s1, root.sg.d1.s1)</code> and <code>example(root.sg.d1.s1, root.sg.d1.s2)</code>.</p><ul><li><strong><code>SELECT example(*, *) from root.sg.d1</code></strong></li></ul><p>Then the result set will include the results of <code>example(root.sg.d1.s1, root.sg.d1.s1)</code>, <code>example(root.sg.d1.s2, root.sg.d1.s1)</code>, <code>example(root.sg.d1.s1, root.sg.d1.s2)</code> and <code>example(root.sg.d1.s2, root.sg.d1.s2)</code>.</p><h3 id="queries-with-key-value-attributes-in-udf-parameters" tabindex="-1"><a class="header-anchor" href="#queries-with-key-value-attributes-in-udf-parameters" aria-hidden="true">#</a> Queries with Key-value Attributes in UDF Parameters</h3><p>You can pass any number of key-value pair parameters to the UDF when constructing a UDF query. The key and value in the key-value pair need to be enclosed in single or double quotes. Note that key-value pair parameters can only be passed in after all time series have been passed in. Here is a set of examples:</p><div class="language-sql line-numbers-mode" data-ext="sql"><pre class="language-sql"><code><span class="token keyword">SELECT</span> example<span class="token punctuation">(</span>s1<span class="token punctuation">,</span> <span class="token string">&#39;key1&#39;</span><span class="token operator">=</span><span class="token string">&#39;value1&#39;</span><span class="token punctuation">,</span> <span class="token string">&#39;key2&#39;</span><span class="token operator">=</span><span class="token string">&#39;value2&#39;</span><span class="token punctuation">)</span><span class="token punctuation">,</span> example<span class="token punctuation">(</span><span class="token operator">*</span><span class="token punctuation">,</span> <span class="token string">&#39;key3&#39;</span><span class="token operator">=</span><span class="token string">&#39;value3&#39;</span><span class="token punctuation">)</span> <span class="token keyword">FROM</span> root<span class="token punctuation">.</span>sg<span class="token punctuation">.</span>d1<span class="token punctuation">;</span>
<span class="token keyword">SELECT</span> example<span class="token punctuation">(</span>s1<span class="token punctuation">,</span> s2<span class="token punctuation">,</span> <span class="token string">&#39;key1&#39;</span><span class="token operator">=</span><span class="token string">&#39;value1&#39;</span><span class="token punctuation">,</span> <span class="token string">&#39;key2&#39;</span><span class="token operator">=</span><span class="token string">&#39;value2&#39;</span><span class="token punctuation">)</span> <span class="token keyword">FROM</span> root<span class="token punctuation">.</span>sg<span class="token punctuation">.</span>d1<span class="token punctuation">;</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div></div></div><h3 id="nested-queries" tabindex="-1"><a class="header-anchor" href="#nested-queries" aria-hidden="true">#</a> Nested Queries</h3><div class="language-sql line-numbers-mode" data-ext="sql"><pre class="language-sql"><code><span class="token keyword">SELECT</span> s1<span class="token punctuation">,</span> s2<span class="token punctuation">,</span> example<span class="token punctuation">(</span>s1<span class="token punctuation">,</span> s2<span class="token punctuation">)</span> <span class="token keyword">FROM</span> root<span class="token punctuation">.</span>sg<span class="token punctuation">.</span>d1<span class="token punctuation">;</span>
<span class="token keyword">SELECT</span> <span class="token operator">*</span><span class="token punctuation">,</span> example<span class="token punctuation">(</span><span class="token operator">*</span><span class="token punctuation">)</span> <span class="token keyword">FROM</span> root<span class="token punctuation">.</span>sg<span class="token punctuation">.</span>d1 <span class="token keyword">DISABLE</span> ALIGN<span class="token punctuation">;</span>
<span class="token keyword">SELECT</span> s1 <span class="token operator">*</span> example<span class="token punctuation">(</span><span class="token operator">*</span> <span class="token operator">/</span> s1 <span class="token operator">+</span> s2<span class="token punctuation">)</span> <span class="token keyword">FROM</span> root<span class="token punctuation">.</span>sg<span class="token punctuation">.</span>d1<span class="token punctuation">;</span>
<span class="token keyword">SELECT</span> s1<span class="token punctuation">,</span> s2<span class="token punctuation">,</span> s1 <span class="token operator">+</span> example<span class="token punctuation">(</span>s1<span class="token punctuation">,</span> s2<span class="token punctuation">)</span><span class="token punctuation">,</span> s1 <span class="token operator">-</span> example<span class="token punctuation">(</span>s1 <span class="token operator">+</span> example<span class="token punctuation">(</span>s1<span class="token punctuation">,</span> s2<span class="token punctuation">)</span> <span class="token operator">/</span> s2<span class="token punctuation">)</span> <span class="token keyword">FROM</span> root<span class="token punctuation">.</span>sg<span class="token punctuation">.</span>d1<span class="token punctuation">;</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h2 id="show-all-registered-udfs" tabindex="-1"><a class="header-anchor" href="#show-all-registered-udfs" aria-hidden="true">#</a> Show All Registered UDFs</h2><div class="language-sql line-numbers-mode" data-ext="sql"><pre class="language-sql"><code><span class="token keyword">SHOW</span> FUNCTIONS
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><h2 id="user-permission-management" tabindex="-1"><a class="header-anchor" href="#user-permission-management" aria-hidden="true">#</a> User Permission Management</h2><p>There are 3 types of user permissions related to UDF:</p><ul><li><code>CREATE_FUNCTION</code>: Only users with this permission are allowed to register UDFs</li><li><code>DROP_FUNCTION</code>: Only users with this permission are allowed to deregister UDFs</li><li><code>READ_TIMESERIES</code>: Only users with this permission are allowed to use UDFs for queries</li></ul>`,40),y=t('<h2 id="configurable-properties" tabindex="-1"><a class="header-anchor" href="#configurable-properties" aria-hidden="true">#</a> Configurable Properties</h2><p>When querying by a UDF, IoTDB may prompt that there is insufficient memory. You can resolve the issue by configuring <code>udf_initial_byte_array_length_for_memory_control</code>, <code>udf_memory_budget_in_mb</code> and <code>udf_reader_transformer_collector_memory_proportion</code> in <code>iotdb-engine.properties</code> and restarting the server.</p><h2 id="contribute-udf" tabindex="-1"><a class="header-anchor" href="#contribute-udf" aria-hidden="true">#</a> Contribute UDF</h2>',3),w=t('<p>This part mainly introduces how external users can contribute their own UDFs to the IoTDB community.</p><h3 id="prerequisites" tabindex="-1"><a class="header-anchor" href="#prerequisites" aria-hidden="true">#</a> Prerequisites</h3><ol><li><p>UDFs must be universal.</p><p>The &quot;universal&quot; mentioned here refers to: UDFs can be widely used in some scenarios. In other words, the UDF function must have reuse value and may be directly used by other users in the community.</p><p>If you are not sure whether the UDF you want to contribute is universal, you can send an email to <code>dev@iotdb.apache.org</code> or create an issue to initiate a discussion.</p></li><li><p>The UDF you are going to contribute has been well tested and can run normally in the production environment.</p></li></ol><h3 id="what-you-need-to-prepare" tabindex="-1"><a class="header-anchor" href="#what-you-need-to-prepare" aria-hidden="true">#</a> What you need to prepare</h3><ol><li>UDF source code</li><li>Test cases</li><li>Instructions</li></ol><h4 id="udf-source-code" tabindex="-1"><a class="header-anchor" href="#udf-source-code" aria-hidden="true">#</a> UDF Source Code</h4><ol><li>Create the UDF main class and related classes in <code>src/main/java/org/apache/iotdb/db/query/udf/builtin</code> or in its subfolders.</li><li>Register your UDF in <code>src/main/java/org/apache/iotdb/db/query/udf/builtin/BuiltinFunction.java</code>.</li></ol><h4 id="test-cases" tabindex="-1"><a class="header-anchor" href="#test-cases" aria-hidden="true">#</a> Test Cases</h4><p>At a minimum, you need to write integration tests for the UDF.</p><p>You can add a test class in <code>server/src/test/java/org/apache/iotdb/db/integration</code>.</p><h4 id="instructions" tabindex="-1"><a class="header-anchor" href="#instructions" aria-hidden="true">#</a> Instructions</h4><p>The instructions need to include: the name and the function of the UDF, the attribute parameters that must be provided when the UDF is executed, the applicable scenarios, and the usage examples, etc.</p><p>The instructions should be added in <code>docs/UserGuide/Operation Manual/DML Data Manipulation Language.md</code>.</p><h3 id="submit-a-pr" tabindex="-1"><a class="header-anchor" href="#submit-a-pr" aria-hidden="true">#</a> Submit a PR</h3>',14),x={href:"https://github.com/apache/iotdb",target:"_blank",rel:"noopener noreferrer"},T={href:"https://iotdb.apache.org/Development/HowToCommit.html",target:"_blank",rel:"noopener noreferrer"},D=a("h2",{id:"known-implementation-udf-libraries",tabindex:"-1"},[a("a",{class:"header-anchor",href:"#known-implementation-udf-libraries","aria-hidden":"true"},"#"),n(" Known Implementation UDF Libraries")],-1),F={href:"https://iotdb.apache.org/UserGuide/Master/UDF-Library/Quick-Start.html",target:"_blank",rel:"noopener noreferrer"},U=t('<h2 id="q-a" tabindex="-1"><a class="header-anchor" href="#q-a" aria-hidden="true">#</a> Q&amp;A</h2><p>Q1: How to modify the registered UDF?</p><p>A1: Assume that the name of the UDF is <code>example</code> and the full class name is <code>org.apache.iotdb.udf.ExampleUDTF</code>, which is introduced by <code>example.jar</code>.</p><ol><li>Unload the registered function by executing <code>DROP FUNCTION example</code>.</li><li>Delete <code>example.jar</code> under <code>iotdb-server-0.13.0-SNAPSHOT-all-bin/ext/udf</code>.</li><li>Modify the logic in <code>org.apache.iotdb.udf.ExampleUDTF</code> and repackage it. The name of the JAR package can still be <code>example.jar</code>.</li><li>Upload the new JAR package to <code>iotdb-server-0.13.0-SNAPSHOT-all-bin/ext/udf</code>.</li><li>Load the new UDF by executing <code>CREATE FUNCTION example AS &quot;org.apache.iotdb.udf.ExampleUDTF&quot;</code>.</li></ol>',4);function S(q,A){const e=o("ExternalLinkIcon"),c=o("RouterLink");return l(),r("div",null,[p(`

    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at
    
        http://www.apache.org/licenses/LICENSE-2.0
    
    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.

`),k,a("p",null,[n("If you use "),a("a",m,[n("Maven"),s(e)]),n(", you can search for the development dependencies listed below from the "),a("a",h,[n("Maven repository"),s(e)]),n(" . Please note that you must select the same dependency version as the target IoTDB server version for development.")]),f,a("p",null,[n("If you use Maven, you can build your own UDF project referring to our "),b,n(" module. You can find the project "),a("a",v,[n("here"),s(e)]),n(".")]),g,a("p",null,[n("For more user permissions related content, please refer to "),s(c,{to:"/UserGuide/V0.13.x/Administration-Management/Administration.html"},{default:u(()=>[n("Account Management Statements")]),_:1}),n(".")]),y,p(" The template is copied and modified from the Apache Doris community"),w,a("p",null,[n("When you have prepared the UDF source code, test cases, and instructions, you are ready to submit a Pull Request (PR) on "),a("a",x,[n("Github"),s(e)]),n(". You can refer to our code contribution guide to submit a PR: "),a("a",T,[n("Pull Request Guide"),s(e)]),n(".")]),D,a("ul",null,[a("li",null,[a("a",F,[n("IoTDB-Quality"),s(e)]),n(", a UDF library about data quality, including data profiling, data quality evalution and data repairing, etc.")])]),U])}const I=i(d,[["render",S],["__file","UDF-User-Defined-Function.html.vue"]]);export{I as default};