Gitiles
Code Review Sign In
asterix-gerrit.ics.uci.edu / incubator-asterixdb-site / 41b806c9252d7d3e699d1f4ef4995824f695a581 / . / content / docs / 0.9.4.1 / sqlpp / builtins.html
blob: f8211a958b6e3e6facb98d705dcc10fba7f80536 [file] [log] [blame]
Ian Maxon41b806c2019-03-07 15:58:20 -0800[diff] [blame^]1<!DOCTYPE html>
2<!--
3 | Generated by Apache Maven Doxia Site Renderer 1.8.1 from target/generated-site/markdown/sqlpp/builtins.md at 2019-03-07
4 | Rendered using Apache Maven Fluido Skin 1.7
5-->
6<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
7 <head>
8 <meta charset="UTF-8" />
9 <meta name="viewport" content="width=device-width, initial-scale=1.0" />
10 <meta name="Date-Revision-yyyymmdd" content="20190307" />
11 <meta http-equiv="Content-Language" content="en" />
12 <title>AsterixDB &#x2013; Builtin Functions</title>
13 <link rel="stylesheet" href="../css/apache-maven-fluido-1.7.min.css" />
14 <link rel="stylesheet" href="../css/site.css" />
15 <link rel="stylesheet" href="../css/print.css" media="print" />
16 <script type="text/javascript" src="../js/apache-maven-fluido-1.7.min.js"></script>
17
18 </head>
19 <body class="topBarDisabled">
20 <div class="container-fluid">
21 <div id="banner">
22 <div class="pull-left"><a href=".././" id="bannerLeft"><img src="../images/asterixlogo.png" alt="AsterixDB"/></a></div>
23 <div class="pull-right"></div>
24 <div class="clear"><hr/></div>
25 </div>
26
27 <div id="breadcrumbs">
28 <ul class="breadcrumb">
29 <li id="publishDate">Last Published: 2019-03-07</li>
30 <li id="projectVersion" class="pull-right">Version: 0.9.4.1</li>
31 <li class="pull-right"><a href="../index.html" title="Documentation Home">Documentation Home</a></li>
32 </ul>
33 </div>
34 <div class="row-fluid">
35 <div id="leftColumn" class="span2">
36 <div class="well sidebar-nav">
37 <ul class="nav nav-list">
38 <li class="nav-header">Get Started - Installation</li>
39 <li><a href="../ncservice.html" title="Option 1: using NCService"><span class="none"></span>Option 1: using NCService</a></li>
40 <li><a href="../ansible.html" title="Option 2: using Ansible"><span class="none"></span>Option 2: using Ansible</a></li>
41 <li><a href="../aws.html" title="Option 3: using Amazon Web Services"><span class="none"></span>Option 3: using Amazon Web Services</a></li>
42 <li class="nav-header">AsterixDB Primer</li>
43 <li><a href="../sqlpp/primer-sqlpp.html" title="Option 1: using SQL++"><span class="none"></span>Option 1: using SQL++</a></li>
44 <li><a href="../aql/primer.html" title="Option 2: using AQL"><span class="none"></span>Option 2: using AQL</a></li>
45 <li class="nav-header">Data Model</li>
46 <li><a href="../datamodel.html" title="The Asterix Data Model"><span class="none"></span>The Asterix Data Model</a></li>
47 <li class="nav-header">Queries - SQL++</li>
48 <li><a href="../sqlpp/manual.html" title="The SQL++ Query Language"><span class="none"></span>The SQL++ Query Language</a></li>
49 <li class="active"><a href="#"><span class="none"></span>Builtin Functions</a></li>
50 <li class="nav-header">Queries - AQL</li>
51 <li><a href="../aql/manual.html" title="The Asterix Query Language (AQL)"><span class="none"></span>The Asterix Query Language (AQL)</a></li>
52 <li><a href="../aql/builtins.html" title="Builtin Functions"><span class="none"></span>Builtin Functions</a></li>
53 <li class="nav-header">API/SDK</li>
54 <li><a href="../api.html" title="HTTP API"><span class="none"></span>HTTP API</a></li>
55 <li><a href="../csv.html" title="CSV Output"><span class="none"></span>CSV Output</a></li>
56 <li class="nav-header">Advanced Features</li>
57 <li><a href="../aql/fulltext.html" title="Support of Full-text Queries"><span class="none"></span>Support of Full-text Queries</a></li>
58 <li><a href="../aql/externaldata.html" title="Accessing External Data"><span class="none"></span>Accessing External Data</a></li>
59 <li><a href="../feeds/tutorial.html" title="Support for Data Ingestion"><span class="none"></span>Support for Data Ingestion</a></li>
60 <li><a href="../udf.html" title="User Defined Functions"><span class="none"></span>User Defined Functions</a></li>
61 <li><a href="../aql/filters.html" title="Filter-Based LSM Index Acceleration"><span class="none"></span>Filter-Based LSM Index Acceleration</a></li>
62 <li><a href="../aql/similarity.html" title="Support of Similarity Queries"><span class="none"></span>Support of Similarity Queries</a></li>
63</ul>
64 <hr />
65 <div id="poweredBy">
66 <div class="clear"></div>
67 <div class="clear"></div>
68 <div class="clear"></div>
69 <div class="clear"></div>
70<a href=".././" title="AsterixDB" class="builtBy"><img class="builtBy" alt="AsterixDB" src="../images/asterixlogo.png" /></a>
71 </div>
72 </div>
73 </div>
74 <div id="bodyColumn" class="span10" >
75<!--
76 ! Licensed to the Apache Software Foundation (ASF) under one
77 ! or more contributor license agreements. See the NOTICE file
78 ! distributed with this work for additional information
79 ! regarding copyright ownership. The ASF licenses this file
80 ! to you under the Apache License, Version 2.0 (the
81 ! "License"); you may not use this file except in compliance
82 ! with the License. You may obtain a copy of the License at
83 !
84 ! http://www.apache.org/licenses/LICENSE-2.0
85 !
86 ! Unless required by applicable law or agreed to in writing,
87 ! software distributed under the License is distributed on an
88 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
89 ! KIND, either express or implied. See the License for the
90 ! specific language governing permissions and limitations
91 ! under the License.
92 !-->
93<h1>Builtin Functions</h1>
94<div class="section">
95<h2><a name="Table_of_Contents"></a><a name="toc" id="toc">Table of Contents</a></h2>
96<ul>
97
98<li><a href="#NumericFunctions">Numeric Functions</a></li>
99<li><a href="#StringFunctions">String Functions</a></li>
100<li><a href="#BinaryFunctions">Binary Functions</a></li>
101<li><a href="#SpatialFunctions">Spatial Functions</a></li>
102<li><a href="#SimilarityFunctions">Similarity Functions</a></li>
103<li><a href="#TokenizingFunctions">Tokenizing Functions</a></li>
104<li><a href="#TemporalFunctions">Temporal Functions</a></li>
105<li><a href="#ObjectFunctions">Object Functions</a></li>
106<li><a href="#AggregateFunctions">Aggregate Functions (Array Functions)</a></li>
107<li><a href="#ComparisonFunctions">Comparison Functions</a></li>
108<li><a href="#TypeFunctions">Type Functions</a></li>
109<li><a href="#ConditionalFunctions">Conditional Functions</a></li>
110<li><a href="#MiscFunctions">Miscellaneous Functions</a></li>
111</ul>
112<p>The system provides various classes of functions to support operations on numeric, string, spatial, and temporal data. This document explains how to use these functions.</p><!--
113 ! Licensed to the Apache Software Foundation (ASF) under one
114 ! or more contributor license agreements. See the NOTICE file
115 ! distributed with this work for additional information
116 ! regarding copyright ownership. The ASF licenses this file
117 ! to you under the Apache License, Version 2.0 (the
118 ! "License"); you may not use this file except in compliance
119 ! with the License. You may obtain a copy of the License at
120 !
121 ! http://www.apache.org/licenses/LICENSE-2.0
122 !
123 ! Unless required by applicable law or agreed to in writing,
124 ! software distributed under the License is distributed on an
125 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
126 ! KIND, either express or implied. See the License for the
127 ! specific language governing permissions and limitations
128 ! under the License.
129 !-->
130</div>
131<div class="section">
132<h2><a name="Numeric_Functions"></a><a name="NumericFunctions" id="NumericFunctions">Numeric Functions</a></h2>
133<div class="section">
134<h3><a name="abs"></a>abs</h3>
135<ul>
136
137<li>
138
139<p>Syntax:</p>
140
141<div>
142<div>
143<pre class="source">abs(numeric_value)
144</pre></div></div>
145</li>
146<li>
147
148<p>Computes the absolute value of the argument.</p>
149</li>
150<li>Arguments:
151<ul>
152
153<li><tt>numeric_value</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value.</li>
154</ul>
155</li>
156<li>Return Value:
157<ul>
158
159<li>The absolute value of the argument with the same type as the input argument,</li>
160<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
161<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
162<li>any other non-numeric input value will cause a type error.</li>
163</ul>
164</li>
165<li>
166
167<p>Example:</p>
168
169<div>
170<div>
171<pre class="source">{ &quot;v1&quot;: abs(2013), &quot;v2&quot;: abs(-4036), &quot;v3&quot;: abs(0), &quot;v4&quot;: abs(float(&quot;-2013.5&quot;)), &quot;v5&quot;: abs(double(&quot;-2013.593823748327284&quot;)) };
172</pre></div></div>
173</li>
174<li>
175
176<p>The expected result is:</p>
177
178<div>
179<div>
180<pre class="source">{ &quot;v1&quot;: 2013, &quot;v2&quot;: 4036, &quot;v3&quot;: 0, &quot;v4&quot;: 2013.5, &quot;v5&quot;: 2013.5938237483274 }
181</pre></div></div>
182</li>
183</ul></div>
184<div class="section">
185<h3><a name="acos"></a>acos</h3>
186<ul>
187
188<li>
189
190<p>Syntax:</p>
191
192<div>
193<div>
194<pre class="source">acos(numeric_value)
195</pre></div></div>
196</li>
197<li>
198
199<p>Computes the arc cosine value of the argument.</p>
200</li>
201<li>Arguments:
202<ul>
203
204<li><tt>numeric_value</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value.</li>
205</ul>
206</li>
207<li>Return Value:
208<ul>
209
210<li>the <tt>double</tt> arc cosine in radians for the argument, if the argument is in the range of -1 (inclusive) to 1 (inclusive),</li>
211<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
212<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
213<li>any other non-numeric input value will cause a type error,</li>
214<li>&#x201c;NaN&#x201d; for other legitimate numeric values.</li>
215</ul>
216</li>
217<li>
218
219<p>Example:</p>
220
221<div>
222<div>
223<pre class="source">{ &quot;v1&quot;: acos(1), &quot;v2&quot;: acos(2), &quot;v3&quot;: acos(0), &quot;v4&quot;: acos(float(&quot;0.5&quot;)), &quot;v5&quot;: acos(double(&quot;-0.5&quot;)) };
224</pre></div></div>
225</li>
226<li>
227
228<p>The expected result is:</p>
229
230<div>
231<div>
232<pre class="source">{ &quot;v1&quot;: 0.0, &quot;v2&quot;: &quot;NaN&quot;, &quot;v3&quot;: 1.5707963267948966, &quot;v4&quot;: 1.0471975511965979, &quot;v5&quot;: 2.0943951023931957 }
233</pre></div></div>
234</li>
235</ul></div>
236<div class="section">
237<h3><a name="asin"></a>asin</h3>
238<ul>
239
240<li>
241
242<p>Syntax:</p>
243
244<div>
245<div>
246<pre class="source">asin(numeric_value)
247</pre></div></div>
248</li>
249<li>
250
251<p>Computes the arc sine value of the argument.</p>
252</li>
253<li>Arguments:
254<ul>
255
256<li><tt>numeric_value</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value.</li>
257</ul>
258</li>
259<li>Return Value:
260<ul>
261
262<li>the <tt>double</tt> arc sin in radians for the argument, if the argument is in the range of -1 (inclusive) to 1 (inclusive),</li>
263<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
264<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
265<li>any other non-numeric input value will cause a type error,</li>
266<li>&#x201c;NaN&#x201d; for other legitimate numeric values.</li>
267</ul>
268</li>
269<li>
270
271<p>Example:</p>
272
273<div>
274<div>
275<pre class="source">{ &quot;v1&quot;: asin(1), &quot;v2&quot;: asin(2), &quot;v3&quot;: asin(0), &quot;v4&quot;: asin(float(&quot;0.5&quot;)), &quot;v5&quot;: asin(double(&quot;-0.5&quot;)) };
276</pre></div></div>
277</li>
278<li>
279
280<p>The expected result is:</p>
281
282<div>
283<div>
284<pre class="source">{ &quot;v1&quot;: 1.5707963267948966, &quot;v2&quot;: &quot;NaN&quot;, &quot;v3&quot;: 0.0, &quot;v4&quot;: 0.5235987755982989, &quot;v5&quot;: -0.5235987755982989 }
285</pre></div></div>
286</li>
287</ul></div>
288<div class="section">
289<h3><a name="atan"></a>atan</h3>
290<ul>
291
292<li>
293
294<p>Syntax:</p>
295
296<div>
297<div>
298<pre class="source">atan(numeric_value)
299</pre></div></div>
300</li>
301<li>
302
303<p>Computes the arc tangent value of the argument.</p>
304</li>
305<li>Arguments:
306<ul>
307
308<li><tt>numeric_value</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value.</li>
309</ul>
310</li>
311<li>Return Value:
312<ul>
313
314<li>the <tt>double</tt> arc tangent in radians for the argument,</li>
315<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
316<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
317<li>any other non-numeric input value will cause a type error.</li>
318</ul>
319</li>
320<li>
321
322<p>Example:</p>
323
324<div>
325<div>
326<pre class="source">{ &quot;v1&quot;: atan(1), &quot;v2&quot;: atan(2), &quot;v3&quot;: atan(0), &quot;v4&quot;: atan(float(&quot;0.5&quot;)), &quot;v5&quot;: atan(double(&quot;1000&quot;)) };
327</pre></div></div>
328</li>
329<li>
330
331<p>The expected result is:</p>
332
333<div>
334<div>
335<pre class="source">{ &quot;v1&quot;: 0.7853981633974483, &quot;v2&quot;: 1.1071487177940904, &quot;v3&quot;: 0.0, &quot;v4&quot;: 0.4636476090008061, &quot;v5&quot;: 1.5697963271282298 }
336</pre></div></div>
337</li>
338</ul></div>
339<div class="section">
340<h3><a name="atan2"></a>atan2</h3>
341<ul>
342
343<li>
344
345<p>Syntax:</p>
346
347<div>
348<div>
349<pre class="source">atan2(numeric_value1, numeric_value2)
350</pre></div></div>
351</li>
352<li>
353
354<p>Computes the arc tangent value of numeric_value2/numeric_value1.</p>
355</li>
356<li>Arguments:
357<ul>
358
359<li><tt>numeric_value1</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value,</li>
360<li><tt>numeric_value2</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value.</li>
361</ul>
362</li>
363<li>Return Value:
364<ul>
365
366<li>the <tt>double</tt> arc tangent in radians for <tt>numeric_value1</tt> and <tt>numeric_value2</tt>,</li>
367<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
368<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
369<li>any other non-numeric input value will cause a type error.</li>
370</ul>
371</li>
372<li>
373
374<p>Example:</p>
375
376<div>
377<div>
378<pre class="source">{ &quot;v1&quot;: atan2(1, 2), &quot;v2&quot;: atan2(0, 4), &quot;v3&quot;: atan2(float(&quot;0.5&quot;), double(&quot;-0.5&quot;)) };
379</pre></div></div>
380</li>
381<li>
382
383<p>The expected result is:</p>
384
385<div>
386<div>
387<pre class="source">{ &quot;v1&quot;: 0.4636476090008061, &quot;v2&quot;: 0.0, &quot;v3&quot;: 2.356194490192345 }
388</pre></div></div>
389</li>
390</ul></div>
391<div class="section">
392<h3><a name="ceil"></a>ceil</h3>
393<ul>
394
395<li>
396
397<p>Syntax:</p>
398
399<div>
400<div>
401<pre class="source">ceil(numeric_value)
402</pre></div></div>
403</li>
404<li>
405
406<p>Computes the smallest (closest to negative infinity) number with no fractional part that is not less than the value of the argument. If the argument is already equal to mathematical integer, then the result is the same as the argument.</p>
407</li>
408<li>Arguments:
409<ul>
410
411<li><tt>numeric_value</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value.</li>
412</ul>
413</li>
414<li>Return Value:
415<ul>
416
417<li>The ceiling value for the given number in the same type as the input argument,</li>
418<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
419<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
420<li>any other non-numeric input value will cause a type error.</li>
421</ul>
422</li>
423<li>
424
425<p>Example:</p>
426
427<div>
428<div>
429<pre class="source">{
430 &quot;v1&quot;: ceil(2013),
431 &quot;v2&quot;: ceil(-4036),
432 &quot;v3&quot;: ceil(0.3),
433 &quot;v4&quot;: ceil(float(&quot;-2013.2&quot;)),
434 &quot;v5&quot;: ceil(double(&quot;-2013.893823748327284&quot;))
435};
436</pre></div></div>
437</li>
438<li>
439
440<p>The expected result is:</p>
441
442<div>
443<div>
444<pre class="source">{ &quot;v1&quot;: 2013, &quot;v2&quot;: -4036, &quot;v3&quot;: 1.0, &quot;v4&quot;: -2013.0, &quot;v5&quot;: -2013.0 }
445</pre></div></div>
446</li>
447</ul></div>
448<div class="section">
449<h3><a name="cos"></a>cos</h3>
450<ul>
451
452<li>
453
454<p>Syntax:</p>
455
456<div>
457<div>
458<pre class="source">cos(numeric_value)
459</pre></div></div>
460</li>
461<li>
462
463<p>Computes the cosine value of the argument.</p>
464</li>
465<li>Arguments:
466<ul>
467
468<li><tt>numeric_value</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value.</li>
469</ul>
470</li>
471<li>Return Value:
472<ul>
473
474<li>the <tt>double</tt> cosine value for the argument,</li>
475<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
476<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
477<li>any other non-numeric input value will cause a type error.</li>
478</ul>
479</li>
480<li>
481
482<p>Example:</p>
483
484<div>
485<div>
486<pre class="source">{ &quot;v1&quot;: cos(1), &quot;v2&quot;: cos(2), &quot;v3&quot;: cos(0), &quot;v4&quot;: cos(float(&quot;0.5&quot;)), &quot;v5&quot;: cos(double(&quot;1000&quot;)) };
487</pre></div></div>
488</li>
489<li>
490
491<p>The expected result is:</p>
492
493<div>
494<div>
495<pre class="source">{ &quot;v1&quot;: 0.5403023058681398, &quot;v2&quot;: -0.4161468365471424, &quot;v3&quot;: 1.0, &quot;v4&quot;: 0.8775825618903728, &quot;v5&quot;: 0.562379076290703 }
496</pre></div></div>
497</li>
498</ul></div>
499<div class="section">
500<h3><a name="degrees"></a>degrees</h3>
501<ul>
502
503<li>
504
505<p>Syntax:</p>
506
507<div>
508<div>
509<pre class="source">degrees(numeric_value)
510</pre></div></div>
511</li>
512<li>
513
514<p>Converts radians to degrees</p>
515</li>
516<li>Arguments:
517<ul>
518
519<li><tt>numeric_value</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value.</li>
520</ul>
521</li>
522<li>Return Value:
523<ul>
524
525<li>The degrees value for the given radians value. The returned value has type <tt>double</tt>,</li>
526<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
527<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
528<li>any other non-numeric input value will cause a type error.</li>
529</ul>
530</li>
531<li>
532
533<p>Example:</p>
534
535<div>
536<div>
537<pre class="source">{ &quot;v1&quot;: degrees(pi()) };
538</pre></div></div>
539</li>
540<li>
541
542<p>The expected result is:</p>
543
544<div>
545<div>
546<pre class="source">{ &quot;v1&quot;: 180.0 }
547</pre></div></div>
548</li>
549</ul></div>
550<div class="section">
551<h3><a name="e"></a>e</h3>
552<ul>
553
554<li>
555
556<p>Syntax:</p>
557
558<div>
559<div>
560<pre class="source">e()
561</pre></div></div>
562</li>
563<li>
564
565<p>Return Value:</p>
566<ul>
567
568<li>e (base of the natural logarithm)</li>
569</ul>
570</li>
571<li>
572
573<p>Example:</p>
574
575<div>
576<div>
577<pre class="source">{ &quot;v1&quot;: e() };
578</pre></div></div>
579</li>
580<li>
581
582<p>The expected result is:</p>
583
584<div>
585<div>
586<pre class="source">{ &quot;v1&quot;: 2.718281828459045 }
587</pre></div></div>
588</li>
589</ul></div>
590<div class="section">
591<h3><a name="exp"></a>exp</h3>
592<ul>
593
594<li>
595
596<p>Syntax:</p>
597
598<div>
599<div>
600<pre class="source">exp(numeric_value)
601</pre></div></div>
602</li>
603<li>
604
605<p>Computes e<sup>numeric_value</sup>.</p>
606</li>
607<li>Arguments:
608<ul>
609
610<li><tt>numeric_value</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value.</li>
611</ul>
612</li>
613<li>Return Value:
614<ul>
615
616<li>e<sup>numeric_value</sup>,</li>
617<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
618<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
619<li>any other non-numeric input value will cause a type error.</li>
620</ul>
621</li>
622<li>
623
624<p>Example:</p>
625
626<div>
627<div>
628<pre class="source">{ &quot;v1&quot;: exp(1), &quot;v2&quot;: exp(2), &quot;v3&quot;: exp(0), &quot;v4&quot;: exp(float(&quot;0.5&quot;)), &quot;v5&quot;: exp(double(&quot;1000&quot;)) };
629</pre></div></div>
630</li>
631<li>
632
633<p>The expected result is:</p>
634
635<div>
636<div>
637<pre class="source">{ &quot;v1&quot;: 2.718281828459045, &quot;v2&quot;: 7.38905609893065, &quot;v3&quot;: 1.0, &quot;v4&quot;: 1.6487212707001282, &quot;v5&quot;: &quot;Infinity&quot; }
638</pre></div></div>
639</li>
640</ul></div>
641<div class="section">
642<h3><a name="floor"></a>floor</h3>
643<ul>
644
645<li>
646
647<p>Syntax:</p>
648
649<div>
650<div>
651<pre class="source">floor(numeric_value)
652</pre></div></div>
653</li>
654<li>
655
656<p>Computes the largest (closest to positive infinity) number with no fractional part that is not greater than the value. If the argument is already equal to mathematical integer, then the result is the same as the argument.</p>
657</li>
658<li>Arguments:
659<ul>
660
661<li><tt>numeric_value</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value.</li>
662</ul>
663</li>
664<li>Return Value:
665<ul>
666
667<li>The floor value for the given number in the same type as the input argument,</li>
668<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
669<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
670<li>any other non-numeric input value will cause a type error.</li>
671</ul>
672</li>
673<li>
674
675<p>Example:</p>
676
677<div>
678<div>
679<pre class="source">{
680 &quot;v1&quot;: floor(2013),
681 &quot;v2&quot;: floor(-4036),
682 &quot;v3&quot;: floor(0.8),
683 &quot;v4&quot;: floor(float(&quot;-2013.2&quot;)),
684 &quot;v5&quot;: floor(double(&quot;-2013.893823748327284&quot;))
685};
686</pre></div></div>
687</li>
688<li>
689
690<p>The expected result is:</p>
691
692<div>
693<div>
694<pre class="source">{ &quot;v1&quot;: 2013, &quot;v2&quot;: -4036, &quot;v3&quot;: 0.0, &quot;v4&quot;: -2014.0, &quot;v5&quot;: -2014.0 }
695</pre></div></div>
696</li>
697</ul></div>
698<div class="section">
699<h3><a name="ln"></a>ln</h3>
700<ul>
701
702<li>
703
704<p>Syntax:</p>
705
706<div>
707<div>
708<pre class="source">ln(numeric_value)
709</pre></div></div>
710</li>
711<li>
712
713<p>Computes log<sub>e</sub>numeric_value.</p>
714</li>
715<li>Arguments:
716<ul>
717
718<li><tt>numeric_value</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value.</li>
719</ul>
720</li>
721<li>Return Value:
722<ul>
723
724<li>log<sub>e</sub>numeric_value,</li>
725<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
726<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
727<li>any other non-numeric input value will cause a type error.</li>
728</ul>
729</li>
730<li>
731
732<p>Example:</p>
733
734<div>
735<div>
736<pre class="source">{ &quot;v1&quot;: ln(1), &quot;v2&quot;: ln(2), &quot;v3&quot;: ln(0), &quot;v4&quot;: ln(float(&quot;0.5&quot;)), &quot;v5&quot;: ln(double(&quot;1000&quot;)) };
737</pre></div></div>
738</li>
739<li>
740
741<p>The expected result is:</p>
742
743<div>
744<div>
745<pre class="source">{ &quot;v1&quot;: 0.0, &quot;v2&quot;: 0.6931471805599453, &quot;v3&quot;: &quot;-Infinity&quot;, &quot;v4&quot;: -0.6931471805599453, &quot;v5&quot;: 6.907755278982137 }
746</pre></div></div>
747</li>
748</ul></div>
749<div class="section">
750<h3><a name="log"></a>log</h3>
751<ul>
752
753<li>
754
755<p>Syntax:</p>
756
757<div>
758<div>
759<pre class="source">log(numeric_value)
760</pre></div></div>
761</li>
762<li>
763
764<p>Computes log<sub>10</sub>numeric_value.</p>
765</li>
766<li>Arguments:
767<ul>
768
769<li><tt>numeric_value</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value.</li>
770</ul>
771</li>
772<li>Return Value:
773<ul>
774
775<li>log<sub>10</sub>numeric_value,</li>
776<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
777<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
778<li>any other non-numeric input value will cause a type error.</li>
779</ul>
780</li>
781<li>
782
783<p>Example:</p>
784
785<div>
786<div>
787<pre class="source">{ &quot;v1&quot;: log(1), &quot;v2&quot;: log(2), &quot;v3&quot;: log(0), &quot;v4&quot;: log(float(&quot;0.5&quot;)), &quot;v5&quot;: log(double(&quot;1000&quot;)) };
788</pre></div></div>
789</li>
790<li>
791
792<p>The expected result is:</p>
793
794<div>
795<div>
796<pre class="source">{ &quot;v1&quot;: 0.0, &quot;v2&quot;: 0.3010299956639812, &quot;v3&quot;: &quot;-Infinity&quot;, &quot;v4&quot;: -0.3010299956639812, &quot;v5&quot;: 3.0 }
797</pre></div></div>
798</li>
799</ul></div>
800<div class="section">
801<h3><a name="pi"></a>pi</h3>
802<ul>
803
804<li>
805
806<p>Syntax:</p>
807
808<div>
809<div>
810<pre class="source">pi()
811</pre></div></div>
812</li>
813<li>
814
815<p>Return Value:</p>
816<ul>
817
818<li>Pi</li>
819</ul>
820</li>
821<li>
822
823<p>Example:</p>
824
825<div>
826<div>
827<pre class="source">{ &quot;v1&quot;: pi() };
828</pre></div></div>
829</li>
830<li>
831
832<p>The expected result is:</p>
833
834<div>
835<div>
836<pre class="source">{ &quot;v1&quot;: 3.141592653589793 }
837</pre></div></div>
838</li>
839</ul></div>
840<div class="section">
841<h3><a name="power"></a>power</h3>
842<ul>
843
844<li>
845
846<p>Syntax:</p>
847
848<div>
849<div>
850<pre class="source">power(numeric_value1, numeric_value2)
851</pre></div></div>
852</li>
853<li>
854
855<p>Computes numeric_value1<sup>numeric_value2</sup>.</p>
856</li>
857<li>Arguments:
858<ul>
859
860<li><tt>numeric_value1</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value,</li>
861<li><tt>numeric_value2</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value.</li>
862</ul>
863</li>
864<li>Return Value:
865<ul>
866
867<li>numeric_value1<sup>numeric_value2</sup>,</li>
868<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
869<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
870<li>any other non-numeric input value will cause a type error.</li>
871</ul>
872</li>
873<li>
874
875<p>Example:</p>
876
877<div>
878<div>
879<pre class="source">{ &quot;v1&quot;: power(1, 2), &quot;v3&quot;: power(0, 4), &quot;v4&quot;: power(float(&quot;0.5&quot;), double(&quot;-0.5&quot;)) };
880</pre></div></div>
881</li>
882<li>
883
884<p>The expected result is:</p>
885
886<div>
887<div>
888<pre class="source">{ &quot;v1&quot;: 1, &quot;v3&quot;: 0, &quot;v4&quot;: 1.4142135623730951 }
889</pre></div></div>
890</li>
891</ul></div>
892<div class="section">
893<h3><a name="radians"></a>radians</h3>
894<ul>
895
896<li>
897
898<p>Syntax:</p>
899
900<div>
901<div>
902<pre class="source">radians(numeric_value)
903</pre></div></div>
904</li>
905<li>
906
907<p>Converts degrees to radians</p>
908</li>
909<li>Arguments:
910<ul>
911
912<li><tt>numeric_value</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value.</li>
913</ul>
914</li>
915<li>Return Value:
916<ul>
917
918<li>The radians value for the given degrees value. The returned value has type <tt>double</tt>,</li>
919<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
920<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
921<li>any other non-numeric input value will cause a type error.</li>
922</ul>
923</li>
924<li>
925
926<p>Example:</p>
927
928<div>
929<div>
930<pre class="source">{ &quot;v1&quot;: radians(180) };
931</pre></div></div>
932</li>
933<li>
934
935<p>The expected result is:</p>
936
937<div>
938<div>
939<pre class="source">{ &quot;v1&quot;: 3.141592653589793 }
940</pre></div></div>
941</li>
942</ul></div>
943<div class="section">
944<h3><a name="round"></a>round</h3>
945<ul>
946
947<li>
948
949<p>Syntax:</p>
950
951<div>
952<div>
953<pre class="source">round(numeric_value)
954</pre></div></div>
955</li>
956<li>
957
958<p>Computes the number with no fractional part that is closest (and also closest to positive infinity) to the argument.</p>
959</li>
960<li>Arguments:
961<ul>
962
963<li><tt>numeric_value</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value.</li>
964</ul>
965</li>
966<li>Return Value:
967<ul>
968
969<li>The rounded value for the given number in the same type as the input argument,</li>
970<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
971<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
972<li>any other non-numeric input value will cause a type error.</li>
973</ul>
974</li>
975<li>
976
977<p>Example:</p>
978
979<div>
980<div>
981<pre class="source">{
982 &quot;v1&quot;: round(2013),
983 &quot;v2&quot;: round(-4036),
984 &quot;v3&quot;: round(0.8),
985 &quot;v4&quot;: round(float(&quot;-2013.256&quot;)),
986 &quot;v5&quot;: round(double(&quot;-2013.893823748327284&quot;))
987};
988</pre></div></div>
989</li>
990<li>
991
992<p>The expected result is:</p>
993
994<div>
995<div>
996<pre class="source">{ &quot;v1&quot;: 2013, &quot;v2&quot;: -4036, &quot;v3&quot;: 1.0, &quot;v4&quot;: -2013.0, &quot;v5&quot;: -2014.0 }
997</pre></div></div>
998</li>
999</ul></div>
1000<div class="section">
1001<h3><a name="sign"></a>sign</h3>
1002<ul>
1003
1004<li>
1005
1006<p>Syntax:</p>
1007
1008<div>
1009<div>
1010<pre class="source">sign(numeric_value)
1011</pre></div></div>
1012</li>
1013<li>
1014
1015<p>Computes the sign of the argument.</p>
1016</li>
1017<li>Arguments:
1018<ul>
1019
1020<li><tt>numeric_value</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value.</li>
1021</ul>
1022</li>
1023<li>Return Value:
1024<ul>
1025
1026<li>the sign (a <tt>tinyint</tt>) of the argument, -1 for negative values, 0 for 0, and 1 for positive values,</li>
1027<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
1028<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
1029<li>any other non-numeric input value will cause a type error.</li>
1030</ul>
1031</li>
1032<li>
1033
1034<p>Example:</p>
1035
1036<div>
1037<div>
1038<pre class="source">{ &quot;v1&quot;: sign(1), &quot;v2&quot;: sign(2), &quot;v3&quot;: sign(0), &quot;v4&quot;: sign(float(&quot;0.5&quot;)), &quot;v5&quot;: sign(double(&quot;-1000&quot;)) };
1039</pre></div></div>
1040</li>
1041<li>
1042
1043<p>The expected result is:</p>
1044
1045<div>
1046<div>
1047<pre class="source">{ &quot;v1&quot;: 1, &quot;v2&quot;: 1, &quot;v3&quot;: 0, &quot;v4&quot;: 1, &quot;v5&quot;: -1 }
1048</pre></div></div>
1049</li>
1050</ul></div>
1051<div class="section">
1052<h3><a name="sin"></a>sin</h3>
1053<ul>
1054
1055<li>
1056
1057<p>Syntax:</p>
1058
1059<div>
1060<div>
1061<pre class="source">sin(numeric_value)
1062</pre></div></div>
1063</li>
1064<li>
1065
1066<p>Computes the sine value of the argument.</p>
1067</li>
1068<li>Arguments:
1069<ul>
1070
1071<li><tt>numeric_value</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value.</li>
1072</ul>
1073</li>
1074<li>Return Value:
1075<ul>
1076
1077<li>the <tt>double</tt> sine value for the argument,</li>
1078<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
1079<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
1080<li>any other non-numeric input value will cause a type error.</li>
1081</ul>
1082</li>
1083<li>
1084
1085<p>Example:</p>
1086
1087<div>
1088<div>
1089<pre class="source">{ &quot;v1&quot;: sin(1), &quot;v2&quot;: sin(2), &quot;v3&quot;: sin(0), &quot;v4&quot;: sin(float(&quot;0.5&quot;)), &quot;v5&quot;: sin(double(&quot;1000&quot;)) };
1090</pre></div></div>
1091</li>
1092<li>
1093
1094<p>The expected result is:</p>
1095
1096<div>
1097<div>
1098<pre class="source">{ &quot;v1&quot;: 0.8414709848078965, &quot;v2&quot;: 0.9092974268256817, &quot;v3&quot;: 0.0, &quot;v4&quot;: 0.479425538604203, &quot;v5&quot;: 0.8268795405320025 }
1099</pre></div></div>
1100</li>
1101</ul></div>
1102<div class="section">
1103<h3><a name="sqrt"></a>sqrt</h3>
1104<ul>
1105
1106<li>
1107
1108<p>Syntax:</p>
1109
1110<div>
1111<div>
1112<pre class="source">sqrt(numeric_value)
1113</pre></div></div>
1114</li>
1115<li>
1116
1117<p>Computes the square root of the argument.</p>
1118</li>
1119<li>Arguments:
1120<ul>
1121
1122<li><tt>numeric_value</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value.</li>
1123</ul>
1124</li>
1125<li>Return Value:
1126<ul>
1127
1128<li>the <tt>double</tt> square root value for the argument,</li>
1129<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
1130<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
1131<li>any other non-numeric input value will cause a type error.</li>
1132</ul>
1133</li>
1134<li>
1135
1136<p>Example:</p>
1137
1138<div>
1139<div>
1140<pre class="source">{ &quot;v1&quot;: sqrt(1), &quot;v2&quot;: sqrt(2), &quot;v3&quot;: sqrt(0), &quot;v4&quot;: sqrt(float(&quot;0.5&quot;)), &quot;v5&quot;: sqrt(double(&quot;1000&quot;)) };
1141</pre></div></div>
1142</li>
1143<li>
1144
1145<p>The expected result is:</p>
1146
1147<div>
1148<div>
1149<pre class="source">{ &quot;v1&quot;: 1.0, &quot;v2&quot;: 1.4142135623730951, &quot;v3&quot;: 0.0, &quot;v4&quot;: 0.7071067811865476, &quot;v5&quot;: 31.622776601683793 }
1150</pre></div></div>
1151</li>
1152</ul></div>
1153<div class="section">
1154<h3><a name="tan"></a>tan</h3>
1155<ul>
1156
1157<li>
1158
1159<p>Syntax:</p>
1160
1161<div>
1162<div>
1163<pre class="source">tan(numeric_value)
1164</pre></div></div>
1165</li>
1166<li>
1167
1168<p>Computes the tangent value of the argument.</p>
1169</li>
1170<li>Arguments:
1171<ul>
1172
1173<li><tt>numeric_value</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value.</li>
1174</ul>
1175</li>
1176<li>Return Value:
1177<ul>
1178
1179<li>the <tt>double</tt> tangent value for the argument,</li>
1180<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
1181<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
1182<li>any other non-numeric input value will cause a type error.</li>
1183</ul>
1184</li>
1185<li>
1186
1187<p>Example:</p>
1188
1189<div>
1190<div>
1191<pre class="source">{ &quot;v1&quot;: tan(1), &quot;v2&quot;: tan(2), &quot;v3&quot;: tan(0), &quot;v4&quot;: tan(float(&quot;0.5&quot;)), &quot;v5&quot;: tan(double(&quot;1000&quot;)) };
1192</pre></div></div>
1193</li>
1194<li>
1195
1196<p>The expected result is:</p>
1197
1198<div>
1199<div>
1200<pre class="source">{ &quot;v1&quot;: 1.5574077246549023, &quot;v2&quot;: -2.185039863261519, &quot;v3&quot;: 0.0, &quot;v4&quot;: 0.5463024898437905, &quot;v5&quot;: 1.4703241557027185 }
1201</pre></div></div>
1202</li>
1203</ul></div>
1204<div class="section">
1205<h3><a name="trunc"></a>trunc</h3>
1206<ul>
1207
1208<li>
1209
1210<p>Syntax:</p>
1211
1212<div>
1213<div>
1214<pre class="source">trunc(numeric_value, number_digits)
1215</pre></div></div>
1216</li>
1217<li>
1218
1219<p>Truncates the number to the given number of integer digits to the right of the decimal point (left if digits is negative). Digits is 0 if not given.</p>
1220</li>
1221<li>Arguments:
1222<ul>
1223
1224<li><tt>numeric_value</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value,</li>
1225<li><tt>number_digits</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt> value.</li>
1226</ul>
1227</li>
1228<li>Return Value:
1229<ul>
1230
1231<li>the <tt>double</tt> tangent value for the argument,</li>
1232<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
1233<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is <tt>missing</tt>,</li>
1234<li>a type error will be raised if:
1235<ul>
1236
1237<li>the first argument is any other non-numeric value,</li>
1238<li>the second argument is any other non-tinyint, non-smallint, non-integer, and non-bigint value.</li>
1239</ul>
1240</li>
1241</ul>
1242</li>
1243<li>
1244
1245<p>Example:</p>
1246
1247<div>
1248<div>
1249<pre class="source">{ &quot;v1&quot;: trunc(1, 1), &quot;v2&quot;: trunc(2, -2), &quot;v3&quot;: trunc(0.122, 2), &quot;v4&quot;: trunc(float(&quot;11.52&quot;), -1), &quot;v5&quot;: trunc(double(&quot;1000.5252&quot;), 3) };
1250</pre></div></div>
1251</li>
1252<li>
1253
1254<p>The expected result is:</p>
1255
1256<div>
1257<div>
1258<pre class="source">{ &quot;v1&quot;: 1, &quot;v2&quot;: 2, &quot;v3&quot;: 0.12, &quot;v4&quot;: 10.0, &quot;v5&quot;: 1000.525 }
1259</pre></div></div>
1260</li>
1261</ul><!--
1262 ! Licensed to the Apache Software Foundation (ASF) under one
1263 ! or more contributor license agreements. See the NOTICE file
1264 ! distributed with this work for additional information
1265 ! regarding copyright ownership. The ASF licenses this file
1266 ! to you under the Apache License, Version 2.0 (the
1267 ! "License"); you may not use this file except in compliance
1268 ! with the License. You may obtain a copy of the License at
1269 !
1270 ! http://www.apache.org/licenses/LICENSE-2.0
1271 !
1272 ! Unless required by applicable law or agreed to in writing,
1273 ! software distributed under the License is distributed on an
1274 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
1275 ! KIND, either express or implied. See the License for the
1276 ! specific language governing permissions and limitations
1277 ! under the License.
1278 !-->
1279</div>
1280<div class="section">
1281<h3><a name="round_half_to_even"></a>round_half_to_even</h3>
1282<ul>
1283
1284<li>
1285
1286<p>Syntax:</p>
1287
1288<div>
1289<div>
1290<pre class="source">round_half_to_even(numeric_value, [precision])
1291</pre></div></div>
1292</li>
1293<li>
1294
1295<p>Computes the closest numeric value to <tt>numeric_value</tt> that is a multiple of ten to the power of minus <tt>precision</tt>. <tt>precision</tt> is optional and by default value <tt>0</tt> is used.</p>
1296</li>
1297<li>Arguments:
1298<ul>
1299
1300<li><tt>numeric_value</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value.</li>
1301<li><tt>precision</tt>: an optional <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt> field representing the number of digits in the fraction of the the result</li>
1302</ul>
1303</li>
1304<li>Return Value:
1305<ul>
1306
1307<li>The rounded value for the given number in the same type as the input argument,</li>
1308<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
1309<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
1310<li>a type error will be raised if:
1311<ul>
1312
1313<li>the first argument is any other non-numeric value,</li>
1314<li>or, the second argument is any other non-tinyint, non-smallint, non-integer, or non-bigint value.</li>
1315</ul>
1316</li>
1317</ul>
1318</li>
1319<li>
1320
1321<p>Example:</p>
1322
1323<div>
1324<div>
1325<pre class="source">{
1326 &quot;v1&quot;: round_half_to_even(2013),
1327 &quot;v2&quot;: round_half_to_even(-4036),
1328 &quot;v3&quot;: round_half_to_even(0.8),
1329 &quot;v4&quot;: round_half_to_even(float(&quot;-2013.256&quot;)),
1330 &quot;v5&quot;: round_half_to_even(double(&quot;-2013.893823748327284&quot;)),
1331 &quot;v6&quot;: round_half_to_even(double(&quot;-2013.893823748327284&quot;), 2),
1332 &quot;v7&quot;: round_half_to_even(2013, 4),
1333 &quot;v8&quot;: round_half_to_even(float(&quot;-2013.256&quot;), 5)
1334};
1335</pre></div></div>
1336</li>
1337<li>
1338
1339<p>The expected result is:</p>
1340
1341<div>
1342<div>
1343<pre class="source">{ &quot;v1&quot;: 2013, &quot;v2&quot;: -4036, &quot;v3&quot;: 1.0, &quot;v4&quot;: -2013.0, &quot;v5&quot;: -2014.0, &quot;v6&quot;: -2013.89, &quot;v7&quot;: 2013, &quot;v8&quot;: -2013.256 }
1344</pre></div></div>
1345</li>
1346</ul><!--
1347 ! Licensed to the Apache Software Foundation (ASF) under one
1348 ! or more contributor license agreements. See the NOTICE file
1349 ! distributed with this work for additional information
1350 ! regarding copyright ownership. The ASF licenses this file
1351 ! to you under the Apache License, Version 2.0 (the
1352 ! "License"); you may not use this file except in compliance
1353 ! with the License. You may obtain a copy of the License at
1354 !
1355 ! http://www.apache.org/licenses/LICENSE-2.0
1356 !
1357 ! Unless required by applicable law or agreed to in writing,
1358 ! software distributed under the License is distributed on an
1359 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
1360 ! KIND, either express or implied. See the License for the
1361 ! specific language governing permissions and limitations
1362 ! under the License.
1363 !-->
1364</div></div>
1365<div class="section">
1366<h2><a name="String_Functions"></a><a name="StringFunctions" id="StringFunctions">String Functions</a></h2>
1367<div class="section">
1368<h3><a name="concat"></a>concat</h3>
1369<ul>
1370
1371<li>
1372
1373<p>Syntax:</p>
1374
1375<div>
1376<div>
1377<pre class="source">concat(string1, string2, ...)
1378</pre></div></div>
1379</li>
1380<li>
1381
1382<p>Returns a concatenated string from arguments.</p>
1383</li>
1384<li>Arguments:
1385<ul>
1386
1387<li><tt>string1</tt>: a string value,</li>
1388<li><tt>string2</tt>: a string value,</li>
1389<li>&#x2026;.</li>
1390</ul>
1391</li>
1392<li>Return Value:
1393<ul>
1394
1395<li>a concatenated string from arguments,</li>
1396<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
1397<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
1398<li>any other non-string input value will cause a type error.</li>
1399</ul>
1400</li>
1401<li>
1402
1403<p>Example:</p>
1404
1405<div>
1406<div>
1407<pre class="source">concat(&quot;test &quot;, &quot;driven &quot;, &quot;development&quot;);
1408</pre></div></div>
1409</li>
1410<li>
1411
1412<p>The expected result is:</p>
1413
1414<div>
1415<div>
1416<pre class="source">&quot;test driven development&quot;
1417</pre></div></div>
1418</li>
1419</ul></div>
1420<div class="section">
1421<h3><a name="contains"></a>contains</h3>
1422<ul>
1423
1424<li>
1425
1426<p>Syntax:</p>
1427
1428<div>
1429<div>
1430<pre class="source">contains(string, substring_to_contain)
1431</pre></div></div>
1432</li>
1433<li>
1434
1435<p>Checks whether the string <tt>string</tt> contains the string <tt>substring_to_contain</tt></p>
1436</li>
1437<li>Arguments:
1438<ul>
1439
1440<li><tt>string</tt> : a <tt>string</tt> that might contain the given substring,</li>
1441<li><tt>substring_to_contain</tt> : a target <tt>string</tt> that might be contained.</li>
1442</ul>
1443</li>
1444<li>Return Value:
1445<ul>
1446
1447<li>a <tt>boolean</tt> value, <tt>true</tt> if <tt>string</tt> contains <tt>substring_to_contain</tt>,</li>
1448<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
1449<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
1450<li>any other non-string input value will cause a type error,</li>
1451<li><tt>false</tt> otherwise.</li>
1452</ul>
1453</li>
1454<li>
1455
1456<p>Note: an <a href="similarity.html#UsingIndexesToSupportSimilarityQueries">n_gram index</a> can be utilized for this function.</p>
1457</li>
1458<li>Example:
1459
1460<div>
1461<div>
1462<pre class="source">{ &quot;v1&quot;: contains(&quot;I like x-phone&quot;, &quot;phone&quot;), &quot;v2&quot;: contains(&quot;one&quot;, &quot;phone&quot;) };
1463</pre></div></div>
1464</li>
1465<li>
1466
1467<p>The expected result is:</p>
1468
1469<div>
1470<div>
1471<pre class="source">{ &quot;v1&quot;: true, &quot;v2&quot;: false }
1472</pre></div></div>
1473</li>
1474</ul></div>
1475<div class="section">
1476<h3><a name="ends_with"></a>ends_with</h3>
1477<ul>
1478
1479<li>
1480
1481<p>Syntax:</p>
1482
1483<div>
1484<div>
1485<pre class="source">ends_with(string, substring_to_end_with)
1486</pre></div></div>
1487</li>
1488<li>
1489
1490<p>Checks whether the string <tt>string</tt> ends with the string <tt>substring_to_end_with</tt>.</p>
1491</li>
1492<li>Arguments:
1493<ul>
1494
1495<li><tt>string</tt> : a <tt>string</tt> that might end with the given string,</li>
1496<li><tt>substring_to_end_with</tt> : a <tt>string</tt> that might be contained as the ending substring.</li>
1497</ul>
1498</li>
1499<li>Return Value:
1500<ul>
1501
1502<li>a <tt>boolean</tt> value, <tt>true</tt> if <tt>string</tt> contains <tt>substring_to_contain</tt>,</li>
1503<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
1504<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
1505<li>any other non-string input value will cause a type error,</li>
1506<li><tt>false</tt> otherwise.</li>
1507</ul>
1508</li>
1509<li>
1510
1511<p>Example:</p>
1512
1513<div>
1514<div>
1515<pre class="source">{
1516 &quot;v1&quot;: ends_with(&quot; love product-b its shortcut_menu is awesome:)&quot;, &quot;:)&quot;),
1517 &quot;v2&quot;: ends_with(&quot; awsome:)&quot;, &quot;:-)&quot;)
1518};
1519</pre></div></div>
1520</li>
1521<li>
1522
1523<p>The expected result is:</p>
1524
1525<div>
1526<div>
1527<pre class="source">{ &quot;v1&quot;: true, &quot;v2&quot;: false }
1528</pre></div></div>
1529</li>
1530</ul></div>
1531<div class="section">
1532<h3><a name="initcap_.28or_title.29"></a>initcap (or title)</h3>
1533<ul>
1534
1535<li>
1536
1537<p>Syntax:</p>
1538
1539<div>
1540<div>
1541<pre class="source">initcap(string)
1542</pre></div></div>
1543</li>
1544<li>
1545
1546<p>Converts a given string <tt>string</tt> so that the first letter of each word is uppercase and every other letter is lowercase. The function has an alias called &#x201c;title&#x201d;.</p>
1547</li>
1548<li>Arguments:
1549<ul>
1550
1551<li><tt>string</tt> : a <tt>string</tt> to be converted.</li>
1552</ul>
1553</li>
1554<li>Return Value:
1555<ul>
1556
1557<li>a <tt>string</tt> as the title form of the given <tt>string</tt>,</li>
1558<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
1559<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
1560<li>any other non-string input value will cause a type error.</li>
1561</ul>
1562</li>
1563<li>
1564
1565<p>Example:</p>
1566
1567<div>
1568<div>
1569<pre class="source">{ &quot;v1&quot;: initcap(&quot;ASTERIXDB is here!&quot;), &quot;v2&quot;: title(&quot;ASTERIXDB is here!&quot;) };
1570</pre></div></div>
1571</li>
1572<li>
1573
1574<p>The expected result is:</p>
1575
1576<div>
1577<div>
1578<pre class="source">{ &quot;v1&quot;: &quot;Asterixdb Is Here!&quot;, &quot;v2&quot;: &quot;Asterixdb Is Here!&quot; }
1579</pre></div></div>
1580</li>
1581</ul></div>
1582<div class="section">
1583<h3><a name="length"></a>length</h3>
1584<ul>
1585
1586<li>
1587
1588<p>Syntax:</p>
1589
1590<div>
1591<div>
1592<pre class="source">length(string)
1593</pre></div></div>
1594</li>
1595<li>
1596
1597<p>Returns the length of the string <tt>string</tt>.</p>
1598</li>
1599<li>Arguments:
1600<ul>
1601
1602<li><tt>string</tt> : a <tt>string</tt> or <tt>null</tt> that represents the string to be checked.</li>
1603</ul>
1604</li>
1605<li>Return Value:
1606<ul>
1607
1608<li>an <tt>bigint</tt> that represents the length of <tt>string</tt>,</li>
1609<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
1610<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
1611<li>any other non-string input value will cause a type error.</li>
1612</ul>
1613</li>
1614<li>
1615
1616<p>Example:</p>
1617
1618<div>
1619<div>
1620<pre class="source">length(&quot;test string&quot;);
1621</pre></div></div>
1622</li>
1623<li>
1624
1625<p>The expected result is:</p>
1626
1627<div>
1628<div>
1629<pre class="source">11
1630</pre></div></div>
1631</li>
1632</ul></div>
1633<div class="section">
1634<h3><a name="lower"></a>lower</h3>
1635<ul>
1636
1637<li>
1638
1639<p>Syntax:</p>
1640
1641<div>
1642<div>
1643<pre class="source">lower(string)
1644</pre></div></div>
1645</li>
1646<li>
1647
1648<p>Converts a given string <tt>string</tt> to its lowercase form.</p>
1649</li>
1650<li>Arguments:
1651<ul>
1652
1653<li><tt>string</tt> : a <tt>string</tt> to be converted.</li>
1654</ul>
1655</li>
1656<li>Return Value:
1657<ul>
1658
1659<li>a <tt>string</tt> as the lowercase form of the given <tt>string</tt>,</li>
1660<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
1661<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
1662<li>any other non-string input value will cause a type error.</li>
1663</ul>
1664</li>
1665<li>
1666
1667<p>Example:</p>
1668
1669<div>
1670<div>
1671<pre class="source">lower(&quot;ASTERIXDB&quot;);
1672</pre></div></div>
1673</li>
1674<li>
1675
1676<p>The expected result is:</p>
1677
1678<div>
1679<div>
1680<pre class="source">&quot;asterixdb&quot;
1681</pre></div></div>
1682</li>
1683</ul></div>
1684<div class="section">
1685<h3><a name="ltrim"></a>ltrim</h3>
1686<ul>
1687
1688<li>
1689
1690<p>Syntax:</p>
1691
1692<div>
1693<div>
1694<pre class="source">ltrim(string[, chars]);
1695</pre></div></div>
1696</li>
1697<li>
1698
1699<p>Returns a new string with all leading characters that appear in <tt>chars</tt> removed. By default, white space is the character to trim.</p>
1700</li>
1701<li>Arguments:
1702<ul>
1703
1704<li><tt>string</tt> : a <tt>string</tt> to be trimmed,</li>
1705<li><tt>chars</tt> : a <tt>string</tt> that contains characters that are used to trim.</li>
1706</ul>
1707</li>
1708<li>Return Value:
1709<ul>
1710
1711<li>a trimmed, new <tt>string</tt>,</li>
1712<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
1713<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
1714<li>any other non-string input value will cause a type error.</li>
1715</ul>
1716</li>
1717<li>
1718
1719<p>Example:</p>
1720
1721<div>
1722<div>
1723<pre class="source">ltrim(&quot;me like x-phone&quot;, &quot;eml&quot;);
1724</pre></div></div>
1725</li>
1726<li>
1727
1728<p>The expected result is:</p>
1729
1730<div>
1731<div>
1732<pre class="source">&quot; like x-phone&quot;
1733</pre></div></div>
1734</li>
1735</ul></div>
1736<div class="section">
1737<h3><a name="position"></a>position</h3>
1738<ul>
1739
1740<li>
1741
1742<p>Syntax:</p>
1743
1744<div>
1745<div>
1746<pre class="source">position(string, string_pattern)
1747</pre></div></div>
1748</li>
1749<li>
1750
1751<p>Returns the first position of <tt>string_pattern</tt> within <tt>string</tt>.</p>
1752</li>
1753<li>Arguments:
1754<ul>
1755
1756<li><tt>string</tt> : a <tt>string</tt> that might contain the pattern,</li>
1757<li><tt>string_pattern</tt> : a pattern <tt>string</tt> to be matched.</li>
1758</ul>
1759</li>
1760<li>Return Value:
1761<ul>
1762
1763<li>the first position that <tt>string_pattern</tt> appears within <tt>string</tt> (starting at 0), or -1 if it does not appear,</li>
1764<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
1765<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
1766<li>any other non-string input value will cause a type error.</li>
1767</ul>
1768</li>
1769<li>
1770
1771<p>Example:</p>
1772
1773<div>
1774<div>
1775<pre class="source">{
1776 &quot;v1&quot;: position(&quot;ppphonepp&quot;, &quot;phone&quot;),
1777 &quot;v2&quot;: position(&quot;hone&quot;, &quot;phone&quot;)
1778};
1779</pre></div></div>
1780</li>
1781<li>
1782
1783<p>The expected result is:</p>
1784
1785<div>
1786<div>
1787<pre class="source">{ &quot;v1&quot;: 3, &quot;v2&quot;: -1 }
1788</pre></div></div>
1789</li>
1790</ul></div>
1791<div class="section">
1792<h3><a name="regexp_contains"></a>regexp_contains</h3>
1793<ul>
1794
1795<li>
1796
1797<p>Syntax:</p>
1798
1799<div>
1800<div>
1801<pre class="source">regexp_contains(string, string_pattern[, string_flags])
1802</pre></div></div>
1803</li>
1804<li>
1805
1806<p>Checks whether the strings <tt>string</tt> contains the regular expression pattern <tt>string_pattern</tt> (a Java regular expression pattern).</p>
1807</li>
1808<li>Arguments:
1809<ul>
1810
1811<li><tt>string</tt> : a <tt>string</tt> that might contain the pattern,</li>
1812<li><tt>string_pattern</tt> : a pattern <tt>string</tt> to be matched,</li>
1813<li><tt>string_flag</tt> : (Optional) a <tt>string</tt> with flags to be used during regular expression matching.
1814<ul>
1815
1816<li>The following modes are enabled with these flags: dotall (s), multiline (m), case_insensitive (i), and comments and whitespace (x).</li>
1817</ul>
1818</li>
1819</ul>
1820</li>
1821<li>Return Value:
1822<ul>
1823
1824<li>a <tt>boolean</tt>, returns <tt>true</tt> if <tt>string</tt> contains the pattern <tt>string_pattern</tt>,</li>
1825<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
1826<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
1827<li>any other non-string input value will cause a type error,</li>
1828<li><tt>false</tt> otherwise.</li>
1829</ul>
1830</li>
1831<li>
1832
1833<p>Example:</p>
1834
1835<div>
1836<div>
1837<pre class="source">{
1838 &quot;v1&quot;: regexp_contains(&quot;pphonepp&quot;, &quot;p*hone&quot;),
1839 &quot;v2&quot;: regexp_contains(&quot;hone&quot;, &quot;p+hone&quot;)
1840}
1841</pre></div></div>
1842</li>
1843<li>
1844
1845<p>The expected result is:</p>
1846
1847<div>
1848<div>
1849<pre class="source">{ &quot;v1&quot;: true, &quot;v2&quot;: false }
1850</pre></div></div>
1851</li>
1852</ul></div>
1853<div class="section">
1854<h3><a name="regexp_like"></a>regexp_like</h3>
1855<ul>
1856
1857<li>
1858
1859<p>Syntax:</p>
1860
1861<div>
1862<div>
1863<pre class="source">regexp_like(string, string_pattern[, string_flags])
1864</pre></div></div>
1865</li>
1866<li>
1867
1868<p>Checks whether the string <tt>string</tt> exactly matches the regular expression pattern <tt>string_pattern</tt> (a Java regular expression pattern).</p>
1869</li>
1870<li>Arguments:
1871<ul>
1872
1873<li><tt>string</tt> : a <tt>string</tt> that might contain the pattern,</li>
1874<li><tt>string_pattern</tt> : a pattern <tt>string</tt> that might be contained,</li>
1875<li><tt>string_flag</tt> : (Optional) a <tt>string</tt> with flags to be used during regular expression matching.
1876<ul>
1877
1878<li>The following modes are enabled with these flags: dotall (s), multiline (m), case_insensitive (i), and comments and whitespace (x).</li>
1879</ul>
1880</li>
1881</ul>
1882</li>
1883<li>Return Value:
1884<ul>
1885
1886<li>a <tt>boolean</tt> value, <tt>true</tt> if <tt>string</tt> contains the pattern <tt>string_pattern</tt>,</li>
1887<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
1888<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
1889<li>any other non-string input value will cause a type error,</li>
1890<li><tt>false</tt> otherwise.</li>
1891</ul>
1892</li>
1893<li>
1894
1895<p>Example:</p>
1896
1897<div>
1898<div>
1899<pre class="source">{
1900 &quot;v1&quot;: regexp_like(&quot; can't stand acast the network is horrible:(&quot;, &quot;.*acast.*&quot;),
1901 &quot;v2&quot;: regexp_like(&quot;acast&quot;, &quot;.*acst.*&quot;)
1902};
1903</pre></div></div>
1904</li>
1905<li>
1906
1907<p>The expected result is:</p>
1908
1909<div>
1910<div>
1911<pre class="source">{ &quot;v1&quot;: true, &quot;v2&quot;: false }
1912</pre></div></div>
1913</li>
1914</ul></div>
1915<div class="section">
1916<h3><a name="regexp_position"></a>regexp_position</h3>
1917<ul>
1918
1919<li>
1920
1921<p>Syntax:</p>
1922
1923<div>
1924<div>
1925<pre class="source">regexp_position(string, string_pattern[, string_flags])
1926</pre></div></div>
1927</li>
1928<li>
1929
1930<p>Returns first position of the regular expression <tt>string_pattern</tt> (a Java regular expression pattern) within <tt>string</tt>.</p>
1931</li>
1932<li>Arguments:
1933<ul>
1934
1935<li><tt>string</tt> : a <tt>string</tt> that might contain the pattern,</li>
1936<li><tt>string_pattern</tt> : a pattern <tt>string</tt> to be matched,</li>
1937<li><tt>string_flag</tt> : (Optional) a <tt>string</tt> with flags to be used during regular expression matching.
1938<ul>
1939
1940<li>The following modes are enabled with these flags: dotall (s), multiline (m), case_insensitive (i), and comments and whitespace (x).</li>
1941</ul>
1942</li>
1943</ul>
1944</li>
1945<li>Return Value:
1946<ul>
1947
1948<li>the first position that the regular expression <tt>string_pattern</tt> appears in <tt>string</tt> (starting at 0), or -1 if it does not appear.</li>
1949<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
1950<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
1951<li>any other non-string input value will cause a type error.</li>
1952</ul>
1953</li>
1954<li>
1955
1956<p>Example:</p>
1957
1958<div>
1959<div>
1960<pre class="source">{
1961 &quot;v1&quot;: regexp_position(&quot;pphonepp&quot;, &quot;p*hone&quot;),
1962 &quot;v2&quot;: regexp_position(&quot;hone&quot;, &quot;p+hone&quot;)
1963};
1964</pre></div></div>
1965</li>
1966<li>
1967
1968<p>The expected result is:</p>
1969
1970<div>
1971<div>
1972<pre class="source">{ &quot;v1&quot;: 1, &quot;v2&quot;: -1 }
1973</pre></div></div>
1974</li>
1975</ul></div>
1976<div class="section">
1977<h3><a name="regexp_replace"></a>regexp_replace</h3>
1978<ul>
1979
1980<li>
1981
1982<p>Syntax:</p>
1983
1984<div>
1985<div>
1986<pre class="source">regexp_replace(string, string_pattern, string_replacement[, string_flags])
1987regexp_replace(string, string_pattern, string_replacement[, replacement_limit])
1988</pre></div></div>
1989</li>
1990<li>
1991
1992<p>Checks whether the string <tt>string</tt> matches the given regular expression pattern <tt>string_pattern</tt> (a Java regular expression pattern), and replaces the matched pattern <tt>string_pattern</tt> with the new pattern <tt>string_replacement</tt>.</p>
1993</li>
1994<li>Arguments:
1995<ul>
1996
1997<li><tt>string</tt> : a <tt>string</tt> that might contain the pattern,</li>
1998<li><tt>string_pattern</tt> : a pattern <tt>string</tt> to be matched,</li>
1999<li><tt>string_replacement</tt> : a pattern <tt>string</tt> to be used as the replacement,</li>
2000<li><tt>string_flag</tt> : (Optional) a <tt>string</tt> with flags to be used during replace.
2001<ul>
2002
2003<li>The following modes are enabled with these flags: dotall (s), multiline (m), case_insensitive (i), and comments and whitespace (x).</li>
2004</ul>
2005</li>
2006<li><tt>replacement_limit</tt>: (Optional) an <tt>integer</tt> specifying the maximum number of replacements to make (if negative then all occurrences will be replaced)</li>
2007</ul>
2008</li>
2009<li>Return Value:
2010<ul>
2011
2012<li>Returns a <tt>string</tt> that is obtained after the replacements,</li>
2013<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2014<li>any other non-string input value will cause a type error,</li>
2015<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value.</li>
2016</ul>
2017</li>
2018<li>
2019
2020<p>Example:</p>
2021
2022<div>
2023<div>
2024<pre class="source">regexp_replace(&quot; like x-phone the voicemail_service is awesome&quot;, &quot; like x-phone&quot;, &quot;like product-a&quot;)
2025</pre></div></div>
2026</li>
2027<li>
2028
2029<p>The expected result is:</p>
2030
2031<div>
2032<div>
2033<pre class="source">&quot;like product-a the voicemail_service is awesome&quot;
2034</pre></div></div>
2035</li>
2036</ul></div>
2037<div class="section">
2038<h3><a name="repeat"></a>repeat</h3>
2039<ul>
2040
2041<li>
2042
2043<p>Syntax:</p>
2044
2045<div>
2046<div>
2047<pre class="source">repeat(string, n)
2048</pre></div></div>
2049</li>
2050<li>
2051
2052<p>Returns a string formed by repeating the input <tt>string</tt> <tt>n</tt> times.</p>
2053</li>
2054<li>Arguments:
2055<ul>
2056
2057<li><tt>string</tt> : a <tt>string</tt> to be repeated,</li>
2058<li><tt>n</tt> : an <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt> value - how many times the string should be repeated.</li>
2059</ul>
2060</li>
2061<li>Return Value:
2062<ul>
2063
2064<li>a string that repeats the input <tt>string</tt> <tt>n</tt> times,</li>
2065<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2066<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2067<li>a type error will be raised if:
2068<ul>
2069
2070<li>the first argument is any other non-string value,</li>
2071<li>or, the second argument is not a <tt>tinyint</tt>, <tt>smallint</tt>, <tt>integer</tt>, or <tt>bigint</tt>.</li>
2072</ul>
2073</li>
2074</ul>
2075</li>
2076<li>
2077
2078<p>Example:</p>
2079
2080<div>
2081<div>
2082<pre class="source">repeat(&quot;test&quot;, 3);
2083</pre></div></div>
2084</li>
2085<li>
2086
2087<p>The expected result is:</p>
2088
2089<div>
2090<div>
2091<pre class="source">&quot;testtesttest&quot;
2092</pre></div></div>
2093</li>
2094</ul></div>
2095<div class="section">
2096<h3><a name="replace"></a>replace</h3>
2097<ul>
2098
2099<li>
2100
2101<p>Syntax:</p>
2102
2103<div>
2104<div>
2105<pre class="source">replace(string, search_string, replacement_string[, limit])
2106</pre></div></div>
2107</li>
2108<li>
2109
2110<p>Finds occurrences of the given substring <tt>search_string</tt> in the input string <tt>string</tt> and replaces them with the new substring <tt>replacement_string</tt>.</p>
2111</li>
2112<li>Arguments:
2113<ul>
2114
2115<li><tt>string</tt> : an input <tt>string</tt>,</li>
2116<li><tt>search_string</tt> : a <tt>string</tt> substring to be searched for,</li>
2117<li><tt>replacement_string</tt> : a <tt>string</tt> to be used as the replacement,</li>
2118<li><tt>limit</tt> : (Optional) an <tt>integer</tt> - maximum number of occurrences to be replaced. If not specified or negative then all occurrences will be replaced</li>
2119</ul>
2120</li>
2121<li>Return Value:
2122<ul>
2123
2124<li>Returns a <tt>string</tt> that is obtained after the replacements,</li>
2125<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2126<li>any other non-string input value or non-integer <tt>limit</tt> will cause a type error,</li>
2127<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value.</li>
2128</ul>
2129</li>
2130<li>
2131
2132<p>Example:</p>
2133
2134<div>
2135<div>
2136<pre class="source">{
2137 &quot;v1&quot;: replace(&quot; like x-phone the voicemail_service is awesome&quot;, &quot; like x-phone&quot;, &quot;like product-a&quot;),
2138 &quot;v2&quot;: replace(&quot;x-phone and x-phone&quot;, &quot;x-phone&quot;, &quot;product-a&quot;, 1)
2139};
2140</pre></div></div>
2141</li>
2142<li>
2143
2144<p>The expected result is:</p>
2145
2146<div>
2147<div>
2148<pre class="source">{
2149 &quot;v1&quot;: &quot;like product-a the voicemail_service is awesome&quot;,
2150 &quot;v2&quot;: &quot;product-a and x-phone&quot;
2151}
2152</pre></div></div>
2153</li>
2154</ul></div>
2155<div class="section">
2156<h3><a name="reverse"></a>reverse</h3>
2157<ul>
2158
2159<li>
2160
2161<p>Syntax:</p>
2162
2163<div>
2164<div>
2165<pre class="source">reverse(string)
2166</pre></div></div>
2167</li>
2168<li>
2169
2170<p>Returns a string formed by reversing characters in the input <tt>string</tt>.</p>
2171</li>
2172<li>Arguments:
2173<ul>
2174
2175<li><tt>string</tt> : a <tt>string</tt> to be reversed</li>
2176</ul>
2177</li>
2178<li>Return Value:
2179<ul>
2180
2181<li>a string containing characters from the the input <tt>string</tt> in the reverse order,</li>
2182<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2183<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2184<li>a type error will be raised if:
2185<ul>
2186
2187<li>the first argument is any other non-string value</li>
2188</ul>
2189</li>
2190</ul>
2191</li>
2192<li>
2193
2194<p>Example:</p>
2195
2196<div>
2197<div>
2198<pre class="source">reverse(&quot;hello&quot;);
2199</pre></div></div>
2200</li>
2201<li>
2202
2203<p>The expected result is:</p>
2204
2205<div>
2206<div>
2207<pre class="source">&quot;olleh&quot;
2208</pre></div></div>
2209</li>
2210</ul></div>
2211<div class="section">
2212<h3><a name="rtrim"></a>rtrim</h3>
2213<ul>
2214
2215<li>
2216
2217<p>Syntax:</p>
2218
2219<div>
2220<div>
2221<pre class="source">rtrim(string[, chars]);
2222</pre></div></div>
2223</li>
2224<li>
2225
2226<p>Returns a new string with all trailing characters that appear in <tt>chars</tt> removed. By default, white space is the character to trim.</p>
2227</li>
2228<li>Arguments:
2229<ul>
2230
2231<li><tt>string</tt> : a <tt>string</tt> to be trimmed,</li>
2232<li><tt>chars</tt> : a <tt>string</tt> that contains characters that are used to trim.</li>
2233</ul>
2234</li>
2235<li>Return Value:
2236<ul>
2237
2238<li>a trimmed, new <tt>string</tt>,</li>
2239<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2240<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2241<li>any other non-string input value will cause a type error.</li>
2242</ul>
2243</li>
2244<li>
2245
2246<p>Example:</p>
2247
2248<div>
2249<div>
2250<pre class="source">{
2251 &quot;v1&quot;: rtrim(&quot;i like x-phone&quot;, &quot;x-phone&quot;),
2252 &quot;v2&quot;: rtrim(&quot;i like x-phone&quot;, &quot;onexph&quot;)
2253};
2254</pre></div></div>
2255</li>
2256<li>
2257
2258<p>The expected result is:</p>
2259
2260<div>
2261<div>
2262<pre class="source">{ &quot;v1&quot;: &quot;i like &quot;, &quot;v2&quot;: &quot;i like &quot; }
2263</pre></div></div>
2264</li>
2265</ul></div>
2266<div class="section">
2267<h3><a name="split"></a>split</h3>
2268<ul>
2269
2270<li>
2271
2272<p>Syntax:</p>
2273
2274<div>
2275<div>
2276<pre class="source">split(string, sep)
2277</pre></div></div>
2278</li>
2279<li>
2280
2281<p>Splits the input <tt>string</tt> into an array of substrings separated by the string <tt>sep</tt>.</p>
2282</li>
2283<li>Arguments:
2284<ul>
2285
2286<li><tt>string</tt> : a <tt>string</tt> to be split.</li>
2287</ul>
2288</li>
2289<li>Return Value:
2290<ul>
2291
2292<li>an array of substrings by splitting the input <tt>string</tt> by <tt>sep</tt>,</li>
2293<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
2294<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
2295<li>any other non-string input value will cause a type error.</li>
2296</ul>
2297</li>
2298<li>
2299
2300<p>Example:</p>
2301
2302<div>
2303<div>
2304<pre class="source">split(&quot;test driven development&quot;, &quot; &quot;);
2305</pre></div></div>
2306</li>
2307<li>
2308
2309<p>The expected result is:</p>
2310
2311<div>
2312<div>
2313<pre class="source">[ &quot;test&quot;, &quot;driven&quot;, &quot;development&quot; ]
2314</pre></div></div>
2315</li>
2316</ul></div>
2317<div class="section">
2318<h3><a name="starts_with"></a>starts_with</h3>
2319<ul>
2320
2321<li>
2322
2323<p>Syntax:</p>
2324
2325<div>
2326<div>
2327<pre class="source">starts_with(string, substring_to_start_with)
2328</pre></div></div>
2329</li>
2330<li>
2331
2332<p>Checks whether the string <tt>string</tt> starts with the string <tt>substring_to_start_with</tt>.</p>
2333</li>
2334<li>Arguments:
2335<ul>
2336
2337<li><tt>string</tt> : a <tt>string</tt> that might start with the given string.</li>
2338<li><tt>substring_to_start_with</tt> : a <tt>string</tt> that might be contained as the starting substring.</li>
2339</ul>
2340</li>
2341<li>Return Value:
2342<ul>
2343
2344<li>a <tt>boolean</tt>, returns <tt>true</tt> if <tt>string</tt> starts with the string <tt>substring_to_start_with</tt>,</li>
2345<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2346<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2347<li>any other non-string input value will cause a type error,</li>
2348<li><tt>false</tt> otherwise.</li>
2349</ul>
2350</li>
2351<li>
2352
2353<p>Example:</p>
2354
2355<div>
2356<div>
2357<pre class="source">{
2358 &quot;v1&quot; : starts_with(&quot; like the plan, amazing&quot;, &quot; like&quot;),
2359 &quot;v2&quot; : starts_with(&quot;I like the plan, amazing&quot;, &quot; like&quot;)
2360};
2361</pre></div></div>
2362</li>
2363<li>
2364
2365<p>The expected result is:</p>
2366
2367<div>
2368<div>
2369<pre class="source">{ &quot;v1&quot;: true, &quot;v2&quot;: false }
2370</pre></div></div>
2371</li>
2372</ul></div>
2373<div class="section">
2374<h3><a name="substr"></a>substr</h3>
2375<ul>
2376
2377<li>
2378
2379<p>Syntax:</p>
2380
2381<div>
2382<div>
2383<pre class="source">substr(string, offset[, length])
2384</pre></div></div>
2385</li>
2386<li>
2387
2388<p>Returns the substring from the given string <tt>string</tt> based on the given start offset <tt>offset</tt> with the optional <tt>length</tt>.</p>
2389</li>
2390<li>Arguments:
2391<ul>
2392
2393<li><tt>string</tt> : a <tt>string</tt> to be extracted,</li>
2394<li><tt>offset</tt> : an <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt> value as the starting offset of the substring in <tt>string</tt> (starting at 0). If negative then counted from the end of the string,</li>
2395<li><tt>length</tt> : (Optional) an an <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt> value as the length of the substring.</li>
2396</ul>
2397</li>
2398<li>Return Value:
2399<ul>
2400
2401<li>a <tt>string</tt> that represents the substring,</li>
2402<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2403<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value, or if the substring could not be obtained because the starting offset is not within string bounds or <tt>length</tt> is negative.</li>
2404<li>a type error will be raised if:
2405<ul>
2406
2407<li>the first argument is any other non-string value,</li>
2408<li>or, the second argument is not a <tt>tinyint</tt>, <tt>smallint</tt>, <tt>integer</tt>, or <tt>bigint</tt>,</li>
2409<li>or, the third argument is not a <tt>tinyint</tt>, <tt>smallint</tt>, <tt>integer</tt>, or <tt>bigint</tt> if the argument is present.</li>
2410</ul>
2411</li>
2412</ul>
2413</li>
2414<li>
2415
2416<p>Example:</p>
2417
2418<div>
2419<div>
2420<pre class="source">substr(&quot;test string&quot;, 6, 3);
2421</pre></div></div>
2422</li>
2423<li>
2424
2425<p>The expected result is:</p>
2426
2427<div>
2428<div>
2429<pre class="source">&quot;str&quot;
2430</pre></div></div>
2431</li>
2432</ul>
2433<p>The function has an alias <tt>substring</tt>.</p></div>
2434<div class="section">
2435<h3><a name="trim"></a>trim</h3>
2436<ul>
2437
2438<li>
2439
2440<p>Syntax:</p>
2441
2442<div>
2443<div>
2444<pre class="source">trim(string[, chars]);
2445</pre></div></div>
2446</li>
2447<li>
2448
2449<p>Returns a new string with all leading characters that appear in <tt>chars</tt> removed. By default, white space is the character to trim.</p>
2450</li>
2451<li>Arguments:
2452<ul>
2453
2454<li><tt>string</tt> : a <tt>string</tt> to be trimmed,</li>
2455<li><tt>chars</tt> : a <tt>string</tt> that contains characters that are used to trim.</li>
2456</ul>
2457</li>
2458<li>Return Value:
2459<ul>
2460
2461<li>a trimmed, new <tt>string</tt>,</li>
2462<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2463<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2464<li>any other non-string input value will cause a type error.</li>
2465</ul>
2466</li>
2467<li>
2468
2469<p>Example:</p>
2470
2471<div>
2472<div>
2473<pre class="source">trim(&quot;i like x-phone&quot;, &quot;xphoen&quot;);
2474</pre></div></div>
2475</li>
2476<li>
2477
2478<p>The expected result is:</p>
2479
2480<div>
2481<div>
2482<pre class="source">&quot; like &quot;
2483</pre></div></div>
2484</li>
2485</ul></div>
2486<div class="section">
2487<h3><a name="upper"></a>upper</h3>
2488<ul>
2489
2490<li>
2491
2492<p>Syntax:</p>
2493
2494<div>
2495<div>
2496<pre class="source">upper(string)
2497</pre></div></div>
2498</li>
2499<li>
2500
2501<p>Converts a given string <tt>string</tt> to its uppercase form.</p>
2502</li>
2503<li>Arguments:
2504<ul>
2505
2506<li><tt>string</tt> : a <tt>string</tt> to be converted.</li>
2507</ul>
2508</li>
2509<li>Return Value:
2510<ul>
2511
2512<li>a <tt>string</tt> as the uppercase form of the given <tt>string</tt>,</li>
2513<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
2514<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
2515<li>any other non-string input value will cause a type error.</li>
2516</ul>
2517</li>
2518<li>
2519
2520<p>Example:</p>
2521
2522<div>
2523<div>
2524<pre class="source">upper(&quot;hello&quot;)
2525</pre></div></div>
2526</li>
2527<li>
2528
2529<p>The expected result is:</p>
2530
2531<div>
2532<div>
2533<pre class="source">&quot;HELLO&quot;
2534</pre></div></div>
2535</li>
2536</ul><!--
2537 ! Licensed to the Apache Software Foundation (ASF) under one
2538 ! or more contributor license agreements. See the NOTICE file
2539 ! distributed with this work for additional information
2540 ! regarding copyright ownership. The ASF licenses this file
2541 ! to you under the Apache License, Version 2.0 (the
2542 ! "License"); you may not use this file except in compliance
2543 ! with the License. You may obtain a copy of the License at
2544 !
2545 ! http://www.apache.org/licenses/LICENSE-2.0
2546 !
2547 ! Unless required by applicable law or agreed to in writing,
2548 ! software distributed under the License is distributed on an
2549 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
2550 ! KIND, either express or implied. See the License for the
2551 ! specific language governing permissions and limitations
2552 ! under the License.
2553 !-->
2554</div>
2555<div class="section">
2556<h3><a name="string_concat"></a>string_concat</h3>
2557<ul>
2558
2559<li>
2560
2561<p>Syntax:</p>
2562
2563<div>
2564<div>
2565<pre class="source">string_concat(array)
2566</pre></div></div>
2567</li>
2568<li>
2569
2570<p>Concatenates an array of strings <tt>array</tt> into a single string.</p>
2571</li>
2572<li>Arguments:
2573<ul>
2574
2575<li><tt>array</tt> : an <tt>array</tt> or <tt>multiset</tt> of <tt>string</tt>s (could be <tt>null</tt> or <tt>missing</tt>) to be concatenated.</li>
2576</ul>
2577</li>
2578<li>Return Value:
2579<ul>
2580
2581<li>the concatenated <tt>string</tt> value,</li>
2582<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
2583<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2584<li><tt>missing</tt> if any element in the input array is <tt>missing</tt>,</li>
2585<li><tt>null</tt> if any element in the input array is <tt>null</tt> but no element in the input array is <tt>missing</tt>,</li>
2586<li>any other non-array input value or non-integer element in the input array will cause a type error.</li>
2587</ul>
2588</li>
2589<li>
2590
2591<p>Example:</p>
2592
2593<div>
2594<div>
2595<pre class="source">string_concat([&quot;ASTERIX&quot;, &quot; &quot;, &quot;ROCKS!&quot;]);
2596</pre></div></div>
2597</li>
2598<li>
2599
2600<p>The expected result is:</p>
2601
2602<div>
2603<div>
2604<pre class="source">&quot;ASTERIX ROCKS!&quot;
2605</pre></div></div>
2606</li>
2607</ul></div>
2608<div class="section">
2609<h3><a name="string_join"></a>string_join</h3>
2610<ul>
2611
2612<li>
2613
2614<p>Syntax:</p>
2615
2616<div>
2617<div>
2618<pre class="source">string_join(array, string)
2619</pre></div></div>
2620</li>
2621<li>
2622
2623<p>Joins an array or multiset of strings <tt>array</tt> with the given separator <tt>string</tt> into a single string.</p>
2624</li>
2625<li>Arguments:
2626<ul>
2627
2628<li><tt>array</tt> : an <tt>array</tt> or <tt>multiset</tt> of strings (could be <tt>null</tt>) to be joined.</li>
2629<li><tt>string</tt> : a <tt>string</tt> to serve as the separator.</li>
2630</ul>
2631</li>
2632<li>Return Value:
2633<ul>
2634
2635<li>the joined <tt>string</tt>,</li>
2636<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2637<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2638<li><tt>missing</tt> if the first argument array contains a <tt>missing</tt>,</li>
2639<li><tt>null</tt> if the first argument array contains a <tt>null</tt> but does not contain a <tt>missing</tt>,</li>
2640<li>a type error will be raised if:
2641<ul>
2642
2643<li>the first argument is any other non-array value, or contains any other non-string value,</li>
2644<li>or, the second argument is any other non-string value.</li>
2645</ul>
2646</li>
2647</ul>
2648</li>
2649<li>
2650
2651<p>Example:</p>
2652
2653<div>
2654<div>
2655<pre class="source">string_join([&quot;ASTERIX&quot;, &quot;ROCKS~&quot;], &quot;!! &quot;);
2656</pre></div></div>
2657</li>
2658<li>
2659
2660<p>The expected result is:</p>
2661
2662<div>
2663<div>
2664<pre class="source">&quot;ASTERIX!! ROCKS~&quot;
2665</pre></div></div>
2666</li>
2667</ul></div>
2668<div class="section">
2669<h3><a name="string_to_codepoint"></a>string_to_codepoint</h3>
2670<ul>
2671
2672<li>
2673
2674<p>Syntax:</p>
2675
2676<div>
2677<div>
2678<pre class="source">string_to_codepoint(string)
2679</pre></div></div>
2680</li>
2681<li>
2682
2683<p>Converts the string <tt>string</tt> to its code_based representation.</p>
2684</li>
2685<li>Arguments:
2686<ul>
2687
2688<li><tt>string</tt> : a <tt>string</tt> that will be converted.</li>
2689</ul>
2690</li>
2691<li>Return Value:
2692<ul>
2693
2694<li>an <tt>array</tt> of the code points for the string <tt>string</tt>,</li>
2695<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
2696<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
2697<li>any other non-string input value will cause a type error.</li>
2698</ul>
2699</li>
2700<li>
2701
2702<p>Example:</p>
2703
2704<div>
2705<div>
2706<pre class="source">string_to_codepoint(&quot;Hello ASTERIX!&quot;);
2707</pre></div></div>
2708</li>
2709<li>
2710
2711<p>The expected result is:</p>
2712
2713<div>
2714<div>
2715<pre class="source">[ 72, 101, 108, 108, 111, 32, 65, 83, 84, 69, 82, 73, 88, 33 ]
2716</pre></div></div>
2717</li>
2718</ul></div>
2719<div class="section">
2720<h3><a name="codepoint_to_string"></a>codepoint_to_string</h3>
2721<ul>
2722
2723<li>
2724
2725<p>Syntax:</p>
2726
2727<div>
2728<div>
2729<pre class="source">codepoint_to_string(array)
2730</pre></div></div>
2731</li>
2732<li>
2733
2734<p>Converts the ordered code_based representation <tt>array</tt> to the corresponding string.</p>
2735</li>
2736<li>Arguments:
2737<ul>
2738
2739<li><tt>array</tt> : an <tt>array</tt> of integer code_points.</li>
2740</ul>
2741</li>
2742<li>Return Value:
2743<ul>
2744
2745<li>a <tt>string</tt> representation of <tt>array</tt>.</li>
2746<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
2747<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
2748<li><tt>missing</tt> if any element in the input array is <tt>missing</tt>,</li>
2749<li><tt>null</tt> if any element in the input array is <tt>null</tt> but no element in the input array is <tt>missing</tt>,</li>
2750<li>any other non-array input value or non-integer element in the input array will cause a type error.</li>
2751</ul>
2752</li>
2753<li>
2754
2755<p>Example:</p>
2756
2757<div>
2758<div>
2759<pre class="source">codepoint_to_string([72, 101, 108, 108, 111, 32, 65, 83, 84, 69, 82, 73, 88, 33]);
2760</pre></div></div>
2761</li>
2762<li>
2763
2764<p>The expected result is:</p>
2765
2766<div>
2767<div>
2768<pre class="source">&quot;Hello ASTERIX!&quot;
2769</pre></div></div>
2770</li>
2771</ul></div>
2772<div class="section">
2773<h3><a name="substring_before"></a>substring_before</h3>
2774<ul>
2775
2776<li>
2777
2778<p>Syntax:</p>
2779
2780<div>
2781<div>
2782<pre class="source">substring_before(string, string_pattern)
2783</pre></div></div>
2784</li>
2785<li>
2786
2787<p>Returns the substring from the given string <tt>string</tt> before the given pattern <tt>string_pattern</tt>.</p>
2788</li>
2789<li>Arguments:
2790<ul>
2791
2792<li><tt>string</tt> : a <tt>string</tt> to be extracted.</li>
2793<li><tt>string_pattern</tt> : a <tt>string</tt> pattern to be searched.</li>
2794</ul>
2795</li>
2796<li>Return Value:
2797<ul>
2798
2799<li>a <tt>string</tt> that represents the substring,</li>
2800<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2801<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2802<li>any other non-string input value will cause a type error.</li>
2803</ul>
2804</li>
2805<li>
2806
2807<p>Example:</p>
2808
2809<div>
2810<div>
2811<pre class="source">substring_before(&quot; like x-phone&quot;, &quot;x-phone&quot;);
2812</pre></div></div>
2813</li>
2814<li>
2815
2816<p>The expected result is:</p>
2817
2818<div>
2819<div>
2820<pre class="source">&quot; like &quot;
2821</pre></div></div>
2822</li>
2823</ul></div>
2824<div class="section">
2825<h3><a name="substring_after"></a>substring_after</h3>
2826<ul>
2827
2828<li>
2829
2830<p>Syntax:</p>
2831<p>substring_after(string, string_pattern);</p>
2832</li>
2833<li>
2834
2835<p>Returns the substring from the given string <tt>string</tt> after the given pattern <tt>string_pattern</tt>.</p>
2836</li>
2837<li>Arguments:
2838<ul>
2839
2840<li><tt>string</tt> : a <tt>string</tt> to be extracted.</li>
2841<li><tt>string_pattern</tt> : a <tt>string</tt> pattern to be searched.</li>
2842</ul>
2843</li>
2844<li>Return Value:
2845<ul>
2846
2847<li>a <tt>string</tt> that represents the substring,</li>
2848<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2849<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2850<li>any other non-string input value will cause a type error.</li>
2851</ul>
2852</li>
2853<li>
2854
2855<p>Example:</p>
2856
2857<div>
2858<div>
2859<pre class="source">substring_after(&quot; like x-phone&quot;, &quot;xph&quot;);
2860</pre></div></div>
2861</li>
2862<li>
2863
2864<p>The expected result is:</p>
2865
2866<div>
2867<div>
2868<pre class="source">&quot;one&quot;
2869</pre></div></div>
2870</li>
2871</ul><!--
2872 ! Licensed to the Apache Software Foundation (ASF) under one
2873 ! or more contributor license agreements. See the NOTICE file
2874 ! distributed with this work for additional information
2875 ! regarding copyright ownership. The ASF licenses this file
2876 ! to you under the Apache License, Version 2.0 (the
2877 ! "License"); you may not use this file except in compliance
2878 ! with the License. You may obtain a copy of the License at
2879 !
2880 ! http://www.apache.org/licenses/LICENSE-2.0
2881 !
2882 ! Unless required by applicable law or agreed to in writing,
2883 ! software distributed under the License is distributed on an
2884 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
2885 ! KIND, either express or implied. See the License for the
2886 ! specific language governing permissions and limitations
2887 ! under the License.
2888 !-->
2889</div></div>
2890<div class="section">
2891<h2><a name="Binary_Functions"></a><a name="BinaryFunctions" id="BinaryFunctions">Binary Functions</a></h2>
2892<div class="section">
2893<h3><a name="parse_binary"></a>parse_binary</h3>
2894<ul>
2895
2896<li>
2897
2898<p>Syntax:</p>
2899<p>parse_binary(string, encoding)</p>
2900</li>
2901<li>
2902
2903<p>Creates a <tt>binary</tt> from an string encoded in <tt>encoding</tt> format.</p>
2904</li>
2905<li>Arguments:
2906<ul>
2907
2908<li><tt>string</tt> : an encoded <tt>string</tt>,</li>
2909<li><tt>encoding</tt> : a string notation specifies the encoding type of the given <tt>string</tt>. Currently we support <tt>hex</tt> and <tt>base64</tt> format.</li>
2910</ul>
2911</li>
2912<li>Return Value:
2913<ul>
2914
2915<li>a <tt>binary</tt> that is decoded from the given <tt>string</tt>,</li>
2916<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2917<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2918<li>any other non-string input value will cause a type error.</li>
2919</ul>
2920</li>
2921<li>
2922
2923<p>Example:</p>
2924<p>[ parse_binary(&#x201c;ABCDEF0123456789&#x201d;,&#x201c;hex&#x201d;), parse_binary(&#x201c;abcdef0123456789&#x201d;,&#x201c;HEX&#x201d;), parse_binary(&#x2018;QXN0ZXJpeAE=&#x2019;,&#x201c;base64&#x201d;) ];</p>
2925</li>
2926<li>
2927
2928<p>The expected result is:</p>
2929<p>[ hex(&#x201c;ABCDEF0123456789&#x201d;), hex(&#x201c;ABCDEF0123456789&#x201d;), hex(&#x201c;4173746572697801&#x201d;) ]</p>
2930</li>
2931</ul></div>
2932<div class="section">
2933<h3><a name="print_binary"></a>print_binary</h3>
2934<ul>
2935
2936<li>
2937
2938<p>Syntax:</p>
2939<p>print_binary(binary, encoding)</p>
2940</li>
2941<li>
2942
2943<p>Prints a <tt>binary</tt> to the required encoding <tt>string</tt> format.</p>
2944</li>
2945<li>Arguments:
2946<ul>
2947
2948<li><tt>binary</tt> : a <tt>binary</tt> data need to be printed.</li>
2949<li><tt>encoding</tt> : a string notation specifies the expected encoding type. Currently we support <tt>hex</tt> and <tt>base64</tt> format.</li>
2950</ul>
2951</li>
2952<li>Return Value:
2953<ul>
2954
2955<li>a <tt>string</tt> that represents the encoded format of a <tt>binary</tt>,</li>
2956<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2957<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2958<li>any other non-string input value will cause a type error.</li>
2959</ul>
2960</li>
2961<li>
2962
2963<p>Example:</p>
2964
2965<div>
2966<div>
2967<pre class="source">[ print_binary(hex(&quot;ABCDEF0123456789&quot;), &quot;base64&quot;), print_binary(base64(&quot;q83vASNFZ4k=&quot;), &quot;hex&quot;) ]
2968</pre></div></div>
2969</li>
2970<li>
2971
2972<p>The expected result are:</p>
2973
2974<div>
2975<div>
2976<pre class="source">[ &quot;q83vASNFZ4k=&quot;, &quot;ABCDEF0123456789&quot; ]
2977</pre></div></div>
2978</li>
2979</ul></div>
2980<div class="section">
2981<h3><a name="binary_length"></a>binary_length</h3>
2982<ul>
2983
2984<li>
2985
2986<p>Syntax:</p>
2987<p>binary_length(binary)</p>
2988</li>
2989<li>
2990
2991<p>Returns the number of bytes storing the binary data.</p>
2992</li>
2993<li>Arguments:
2994<ul>
2995
2996<li><tt>binary</tt> : a <tt>binary</tt> value to be checked.</li>
2997</ul>
2998</li>
2999<li>Return Value:
3000<ul>
3001
3002<li>an <tt>bigint</tt> that represents the number of bytes,</li>
3003<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
3004<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
3005<li>any other non-binary input value will cause a type error.</li>
3006</ul>
3007</li>
3008<li>
3009
3010<p>Example:</p>
3011
3012<div>
3013<div>
3014<pre class="source">binary_length(hex(&quot;00AA&quot;))
3015</pre></div></div>
3016</li>
3017<li>
3018
3019<p>The expected result is:</p>
3020<p>2</p>
3021</li>
3022</ul></div>
3023<div class="section">
3024<h3><a name="sub_binary"></a>sub_binary</h3>
3025<ul>
3026
3027<li>
3028
3029<p>Syntax:</p>
3030<p>sub_binary(binary, offset[, length])</p>
3031</li>
3032<li>
3033
3034<p>Returns the sub binary from the given <tt>binary</tt> based on the given start offset with the optional <tt>length</tt>.</p>
3035</li>
3036<li>Arguments:
3037<ul>
3038
3039<li><tt>binary</tt> : a <tt>binary</tt> to be extracted,</li>
3040<li><tt>offset</tt> : a <tt>tinyint</tt>, <tt>smallint</tt>, <tt>integer</tt>, or <tt>bigint</tt> value as the starting offset of the sub binary in <tt>binary</tt> (starting at 0),</li>
3041<li><tt>length</tt> : (Optional) a <tt>tinyint</tt>, <tt>smallint</tt>, <tt>integer</tt>, or <tt>bigint</tt> value as the length of the sub binary.</li>
3042</ul>
3043</li>
3044<li>Return Value:
3045<ul>
3046
3047<li>a <tt>binary</tt> that represents the sub binary,</li>
3048<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3049<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3050<li>a type error will be raised if:
3051<ul>
3052
3053<li>the first argument is any other non-binary value,</li>
3054<li>or, the second argument is any other non-integer value,</li>
3055<li>or, the third argument is any other non-integer value, if it is present.</li>
3056</ul>
3057</li>
3058</ul>
3059</li>
3060<li>
3061
3062<p>Example:</p>
3063
3064<div>
3065<div>
3066<pre class="source">sub_binary(hex(&quot;AABBCCDD&quot;), 4);
3067</pre></div></div>
3068</li>
3069<li>
3070
3071<p>The expected result is</p>
3072
3073<div>
3074<div>
3075<pre class="source">hex(&quot;DD&quot;)
3076</pre></div></div>
3077</li>
3078</ul></div>
3079<div class="section">
3080<h3><a name="binary_concat"></a>binary_concat</h3>
3081<ul>
3082
3083<li>
3084
3085<p>Syntax:</p>
3086<p>binary_concat(array)</p>
3087</li>
3088<li>
3089
3090<p>Concatenates a binary <tt>array</tt> or <tt>multiset</tt> into a single binary.</p>
3091</li>
3092<li>Arguments:
3093<ul>
3094
3095<li><tt>array</tt> : an <tt>array</tt> or <tt>multiset</tt> of binaries (could be <tt>null</tt> or <tt>missing</tt>) to be concatenated.</li>
3096</ul>
3097</li>
3098<li>Return Value :
3099<ul>
3100
3101<li>the concatenated <tt>binary</tt> value,</li>
3102<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
3103<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
3104<li><tt>missing</tt> if any element in the input array is <tt>missing</tt>,</li>
3105<li><tt>null</tt> if any element in the input array is <tt>null</tt> but no element in the input array is <tt>missing</tt>,</li>
3106<li>any other non-array input value or non-binary element in the input array will cause a type error.</li>
3107</ul>
3108</li>
3109<li>
3110
3111<p>Example:</p>
3112<p>binary_concat([hex(&#x201c;42&#x201d;), hex(&quot;&quot;), hex(&#x2018;42&#x2019;)]);</p>
3113</li>
3114<li>
3115
3116<p>The expected result is</p>
3117<p>hex(&#x201c;4242&#x201d;)</p>
3118</li>
3119</ul><!--
3120 ! Licensed to the Apache Software Foundation (ASF) under one
3121 ! or more contributor license agreements. See the NOTICE file
3122 ! distributed with this work for additional information
3123 ! regarding copyright ownership. The ASF licenses this file
3124 ! to you under the Apache License, Version 2.0 (the
3125 ! "License"); you may not use this file except in compliance
3126 ! with the License. You may obtain a copy of the License at
3127 !
3128 ! http://www.apache.org/licenses/LICENSE-2.0
3129 !
3130 ! Unless required by applicable law or agreed to in writing,
3131 ! software distributed under the License is distributed on an
3132 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
3133 ! KIND, either express or implied. See the License for the
3134 ! specific language governing permissions and limitations
3135 ! under the License.
3136 !-->
3137</div></div>
3138<div class="section">
3139<h2><a name="Spatial_Functions"></a><a name="SpatialFunctions" id="SpatialFunctions">Spatial Functions</a></h2>
3140<div class="section">
3141<h3><a name="create_point"></a>create_point</h3>
3142<ul>
3143
3144<li>
3145
3146<p>Syntax:</p>
3147
3148<div>
3149<div>
3150<pre class="source">create_point(x, y)
3151</pre></div></div>
3152</li>
3153<li>
3154
3155<p>Creates the primitive type <tt>point</tt> using an <tt>x</tt> and <tt>y</tt> value.</p>
3156</li>
3157<li>Arguments:</li>
3158<li><tt>x</tt> : a <tt>double</tt> that represents the x-coordinate,</li>
3159<li><tt>y</tt> : a <tt>double</tt> that represents the y-coordinate.</li>
3160<li>Return Value:</li>
3161<li>a <tt>point</tt> representing the ordered pair (<tt>x</tt>, <tt>y</tt>),</li>
3162<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3163<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3164<li>any other non-double input value will cause a type error.</li>
3165<li>
3166
3167<p>Example:</p>
3168
3169<div>
3170<div>
3171<pre class="source">{ &quot;point&quot;: create_point(30.0,70.0) };
3172</pre></div></div>
3173</li>
3174<li>
3175
3176<p>The expected result is:</p>
3177
3178<div>
3179<div>
3180<pre class="source">{ &quot;point&quot;: point(&quot;30.0,70.0&quot;) }
3181</pre></div></div>
3182</li>
3183</ul></div>
3184<div class="section">
3185<h3><a name="create_line"></a>create_line</h3>
3186<ul>
3187
3188<li>
3189
3190<p>Syntax:</p>
3191
3192<div>
3193<div>
3194<pre class="source">create_line(point1, point2)
3195</pre></div></div>
3196</li>
3197<li>
3198
3199<p>Creates the primitive type <tt>line</tt> using <tt>point1</tt> and <tt>point2</tt>.</p>
3200</li>
3201<li>Arguments:
3202<ul>
3203
3204<li><tt>point1</tt> : a <tt>point</tt> that represents the start point of the line.</li>
3205<li><tt>point2</tt> : a <tt>point</tt> that represents the end point of the line.</li>
3206</ul>
3207</li>
3208<li>Return Value:
3209<ul>
3210
3211<li>a spatial <tt>line</tt> created using the points provided in <tt>point1</tt> and <tt>point2</tt>,</li>
3212<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3213<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3214<li>any other non-point input value will cause a type error.</li>
3215</ul>
3216</li>
3217<li>
3218
3219<p>Example:</p>
3220
3221<div>
3222<div>
3223<pre class="source">{ &quot;line&quot;: create_line(create_point(30.0,70.0), create_point(50.0,90.0)) };
3224</pre></div></div>
3225</li>
3226<li>
3227
3228<p>The expected result is:</p>
3229
3230<div>
3231<div>
3232<pre class="source">{ &quot;line&quot;: line(&quot;30.0,70.0 50.0,90.0&quot;) }
3233</pre></div></div>
3234</li>
3235</ul></div>
3236<div class="section">
3237<h3><a name="create_rectangle"></a>create_rectangle</h3>
3238<ul>
3239
3240<li>
3241
3242<p>Syntax:</p>
3243
3244<div>
3245<div>
3246<pre class="source">create_rectangle(point1, point2)
3247</pre></div></div>
3248</li>
3249<li>
3250
3251<p>Creates the primitive type <tt>rectangle</tt> using <tt>point1</tt> and <tt>point2</tt>.</p>
3252</li>
3253<li>Arguments:
3254<ul>
3255
3256<li><tt>point1</tt> : a <tt>point</tt> that represents the lower_left point of the rectangle.</li>
3257<li><tt>point2</tt> : a <tt>point</tt> that represents the upper_right point of the rectangle.</li>
3258</ul>
3259</li>
3260<li>Return Value:
3261<ul>
3262
3263<li>a spatial <tt>rectangle</tt> created using the points provided in <tt>point1</tt> and <tt>point2</tt>,</li>
3264<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3265<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3266<li>any other non-point input value will cause a type error.</li>
3267</ul>
3268</li>
3269<li>
3270
3271<p>Example:</p>
3272
3273<div>
3274<div>
3275<pre class="source">{ &quot;rectangle&quot;: create_rectangle(create_point(30.0,70.0), create_point(50.0,90.0)) };
3276</pre></div></div>
3277</li>
3278<li>
3279
3280<p>The expected result is:</p>
3281
3282<div>
3283<div>
3284<pre class="source">{ &quot;rectangle&quot;: rectangle(&quot;30.0,70.0 50.0,90.0&quot;) }
3285</pre></div></div>
3286</li>
3287</ul></div>
3288<div class="section">
3289<h3><a name="create_circle"></a>create_circle</h3>
3290<ul>
3291
3292<li>
3293
3294<p>Syntax:</p>
3295
3296<div>
3297<div>
3298<pre class="source">create_circle(point, radius)
3299</pre></div></div>
3300</li>
3301<li>
3302
3303<p>Creates the primitive type <tt>circle</tt> using <tt>point</tt> and <tt>radius</tt>.</p>
3304</li>
3305<li>Arguments:
3306<ul>
3307
3308<li><tt>point</tt> : a <tt>point</tt> that represents the center of the circle.</li>
3309<li><tt>radius</tt> : a <tt>double</tt> that represents the radius of the circle.</li>
3310</ul>
3311</li>
3312<li>Return Value:
3313<ul>
3314
3315<li>a spatial <tt>circle</tt> created using the center point and the radius provided in <tt>point</tt> and <tt>radius</tt>.</li>
3316<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3317<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3318<li>a type error will be raised if:
3319<ul>
3320
3321<li>the first argument is any other non-point value,</li>
3322<li>or, the second argument is any other non-double value.</li>
3323</ul>
3324</li>
3325</ul>
3326</li>
3327<li>
3328
3329<p>Example:</p>
3330
3331<div>
3332<div>
3333<pre class="source">{ &quot;circle&quot;: create_circle(create_point(30.0,70.0), 5.0) }
3334</pre></div></div>
3335</li>
3336<li>
3337
3338<p>The expected result is:</p>
3339
3340<div>
3341<div>
3342<pre class="source">{ &quot;circle&quot;: circle(&quot;30.0,70.0 5.0&quot;) }
3343</pre></div></div>
3344</li>
3345</ul></div>
3346<div class="section">
3347<h3><a name="create_polygon"></a>create_polygon</h3>
3348<ul>
3349
3350<li>
3351
3352<p>Syntax:</p>
3353
3354<div>
3355<div>
3356<pre class="source">create_polygon(array)
3357</pre></div></div>
3358</li>
3359<li>
3360
3361<p>Creates the primitive type <tt>polygon</tt> using the double values provided in the argument <tt>array</tt>. Each two consecutive double values represent a point starting from the first double value in the array. Note that at least six double values should be specified, meaning a total of three points.</p>
3362</li>
3363<li>Arguments:
3364<ul>
3365
3366<li><tt>array</tt> : an array of doubles representing the points of the polygon.</li>
3367</ul>
3368</li>
3369<li>Return Value:
3370<ul>
3371
3372<li>a <tt>polygon</tt>, represents a spatial simple polygon created using the points provided in <tt>array</tt>.</li>
3373<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
3374<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
3375<li><tt>missing</tt> if any element in the input array is <tt>missing</tt>,</li>
3376<li><tt>null</tt> if any element in the input array is <tt>null</tt> but no element in the input array is <tt>missing</tt>,</li>
3377<li>any other non-array input value or non-double element in the input array will cause a type error.</li>
3378</ul>
3379</li>
3380<li>
3381
3382<p>Example:</p>
3383
3384<div>
3385<div>
3386<pre class="source">{ &quot;polygon&quot;: create_polygon([1.0,1.0,2.0,2.0,3.0,3.0,4.0,4.0]) };
3387</pre></div></div>
3388</li>
3389<li>
3390
3391<p>The expected result is:</p>
3392
3393<div>
3394<div>
3395<pre class="source">{ &quot;polygon&quot;: polygon(&quot;1.0,1.0 2.0,2.0 3.0,3.0 4.0,4.0&quot;) }
3396</pre></div></div>
3397</li>
3398</ul></div>
3399<div class="section">
3400<h3><a name="get_x.2Fget_y"></a>get_x/get_y</h3>
3401<ul>
3402
3403<li>
3404
3405<p>Syntax:</p>
3406
3407<div>
3408<div>
3409<pre class="source">get_x(point) or get_y(point)
3410</pre></div></div>
3411</li>
3412<li>
3413
3414<p>Returns the x or y coordinates of a point <tt>point</tt>.</p>
3415</li>
3416<li>Arguments:
3417<ul>
3418
3419<li><tt>point</tt> : a <tt>point</tt>.</li>
3420</ul>
3421</li>
3422<li>Return Value:
3423<ul>
3424
3425<li>a <tt>double</tt> representing the x or y coordinates of the point <tt>point</tt>,</li>
3426<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
3427<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
3428<li>any other non-point input value will cause a type error.</li>
3429</ul>
3430</li>
3431<li>
3432
3433<p>Example:</p>
3434
3435<div>
3436<div>
3437<pre class="source">{ &quot;x_coordinate&quot;: get_x(create_point(2.3,5.0)), &quot;y_coordinate&quot;: get_y(create_point(2.3,5.0)) };
3438</pre></div></div>
3439</li>
3440<li>
3441
3442<p>The expected result is:</p>
3443
3444<div>
3445<div>
3446<pre class="source">{ &quot;x_coordinate&quot;: 2.3, &quot;y_coordinate&quot;: 5.0 }
3447</pre></div></div>
3448</li>
3449</ul></div>
3450<div class="section">
3451<h3><a name="get_points"></a>get_points</h3>
3452<ul>
3453
3454<li>
3455
3456<p>Syntax:</p>
3457
3458<div>
3459<div>
3460<pre class="source">get_points(spatial_object)
3461</pre></div></div>
3462</li>
3463<li>
3464
3465<p>Returns an ordered array of the points forming the spatial object <tt>spatial_object</tt>.</p>
3466</li>
3467<li>Arguments:
3468<ul>
3469
3470<li><tt>spatial_object</tt> : a <tt>point</tt>, <tt>line</tt>, <tt>rectangle</tt>, <tt>circle</tt>, or <tt>polygon</tt>.</li>
3471</ul>
3472</li>
3473<li>Return Value:
3474<ul>
3475
3476<li>an <tt>array</tt> of the points forming the spatial object <tt>spatial_object</tt>,</li>
3477<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
3478<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
3479<li>any other non-spatial-object input value will cause a type error.</li>
3480</ul>
3481</li>
3482<li>
3483
3484<p>Example:</p>
3485
3486<div>
3487<div>
3488<pre class="source">get_points(create_polygon([1.0,1.0,2.0,2.0,3.0,3.0,4.0,4.0]))
3489</pre></div></div>
3490</li>
3491<li>
3492
3493<p>The expected result is:</p>
3494
3495<div>
3496<div>
3497<pre class="source">[ point(&quot;1.0,1.0&quot;), point(&quot;2.0,2.0&quot;), point(&quot;3.0,3.0&quot;), point(&quot;4.0,4.0&quot;) ]
3498</pre></div></div>
3499</li>
3500</ul></div>
3501<div class="section">
3502<h3><a name="get_center.2Fget_radius"></a>get_center/get_radius</h3>
3503<ul>
3504
3505<li>
3506
3507<p>Syntax:</p>
3508
3509<div>
3510<div>
3511<pre class="source">get_center(circle_expression) or get_radius(circle_expression)
3512</pre></div></div>
3513</li>
3514<li>
3515
3516<p>Returns the center and the radius of a circle <tt>circle_expression</tt>, respectively.</p>
3517</li>
3518<li>Arguments:
3519<ul>
3520
3521<li><tt>circle_expression</tt> : a <tt>circle</tt>.</li>
3522</ul>
3523</li>
3524<li>Return Value:
3525<ul>
3526
3527<li>a <tt>point</tt> or <tt>double</tt>, represent the center or radius of the circle <tt>circle_expression</tt>.</li>
3528<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
3529<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
3530<li>any other non-circle input value will cause a type error.</li>
3531</ul>
3532</li>
3533<li>
3534
3535<p>Example:</p>
3536
3537<div>
3538<div>
3539<pre class="source">{
3540 &quot;circle_radius&quot;: get_radius(create_circle(create_point(6.0,3.0), 1.0)),
3541 &quot;circle_center&quot;: get_center(create_circle(create_point(6.0,3.0), 1.0))
3542};
3543</pre></div></div>
3544</li>
3545<li>
3546
3547<p>The expected result is:</p>
3548
3549<div>
3550<div>
3551<pre class="source">{ &quot;circle_radius&quot;: 1.0, &quot;circle_center&quot;: point(&quot;6.0,3.0&quot;) }
3552</pre></div></div>
3553</li>
3554</ul></div>
3555<div class="section">
3556<h3><a name="spatial_distance"></a>spatial_distance</h3>
3557<ul>
3558
3559<li>
3560
3561<p>Syntax:</p>
3562
3563<div>
3564<div>
3565<pre class="source">spatial_distance(point1, point2)
3566</pre></div></div>
3567</li>
3568<li>
3569
3570<p>Returns the Euclidean distance between <tt>point1</tt> and <tt>point2</tt>.</p>
3571</li>
3572<li>Arguments:
3573<ul>
3574
3575<li><tt>point1</tt> : a <tt>point</tt>.</li>
3576<li><tt>point2</tt> : a <tt>point</tt>.</li>
3577</ul>
3578</li>
3579<li>Return Value:
3580<ul>
3581
3582<li>a <tt>double</tt> as the Euclidean distance between <tt>point1</tt> and <tt>point2</tt>.</li>
3583<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3584<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3585<li>any other non-point input value will cause a type error.</li>
3586</ul>
3587</li>
3588<li>
3589
3590<p>Example:</p>
3591
3592<div>
3593<div>
3594<pre class="source">spatial_distance(point(&quot;47.44,80.65&quot;), create_point(30.0,70.0));
3595</pre></div></div>
3596</li>
3597<li>
3598
3599<p>The expected result is:</p>
3600
3601<div>
3602<div>
3603<pre class="source">20.434678857275934
3604</pre></div></div>
3605</li>
3606</ul></div>
3607<div class="section">
3608<h3><a name="spatial_area"></a>spatial_area</h3>
3609<ul>
3610
3611<li>
3612
3613<p>Syntax:</p>
3614
3615<div>
3616<div>
3617<pre class="source">spatial_area(spatial_2d_expression)
3618</pre></div></div>
3619</li>
3620<li>
3621
3622<p>Returns the spatial area of <tt>spatial_2d_expression</tt>.</p>
3623</li>
3624<li>Arguments:
3625<ul>
3626
3627<li><tt>spatial_2d_expression</tt> : a <tt>rectangle</tt>, <tt>circle</tt>, or <tt>polygon</tt>.</li>
3628</ul>
3629</li>
3630<li>Return Value:
3631<ul>
3632
3633<li>a <tt>double</tt> representing the area of <tt>spatial_2d_expression</tt>.</li>
3634<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
3635<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
3636<li>any other non-2d-spatial-object will cause a type error.</li>
3637</ul>
3638</li>
3639<li>
3640
3641<p>Example:</p>
3642
3643<div>
3644<div>
3645<pre class="source">spatial_area(create_circle(create_point(0.0,0.0), 5.0));
3646</pre></div></div>
3647</li>
3648<li>
3649
3650<p>The expected result is:</p>
3651
3652<div>
3653<div>
3654<pre class="source">78.53981625
3655</pre></div></div>
3656</li>
3657</ul></div>
3658<div class="section">
3659<h3><a name="spatial_intersect"></a>spatial_intersect</h3>
3660<ul>
3661
3662<li>
3663
3664<p>Syntax:</p>
3665
3666<div>
3667<div>
3668<pre class="source">spatial_intersect(spatial_object1, spatial_object2)
3669</pre></div></div>
3670</li>
3671<li>
3672
3673<p>Checks whether <tt>@arg1</tt> and <tt>@arg2</tt> spatially intersect each other.</p>
3674</li>
3675<li>Arguments:
3676<ul>
3677
3678<li><tt>spatial_object1</tt> : a <tt>point</tt>, <tt>line</tt>, <tt>rectangle</tt>, <tt>circle</tt>, or <tt>polygon</tt>.</li>
3679<li><tt>spatial_object2</tt> : a <tt>point</tt>, <tt>line</tt>, <tt>rectangle</tt>, <tt>circle</tt>, or <tt>polygon</tt>.</li>
3680</ul>
3681</li>
3682<li>Return Value:
3683<ul>
3684
3685<li>a <tt>boolean</tt> representing whether <tt>spatial_object1</tt> and <tt>spatial_object2</tt> spatially overlap with each other,</li>
3686<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3687<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3688<li>any other non-spatial-object input value will cause a type error.</li>
3689</ul>
3690</li>
3691<li>
3692
3693<p>Example:</p>
3694
3695<div>
3696<div>
3697<pre class="source">spatial_intersect(point(&quot;39.28,70.48&quot;), create_rectangle(create_point(30.0,70.0), create_point(40.0,80.0)));
3698</pre></div></div>
3699</li>
3700<li>
3701
3702<p>The expected result is:</p>
3703
3704<div>
3705<div>
3706<pre class="source">true
3707</pre></div></div>
3708</li>
3709</ul></div>
3710<div class="section">
3711<h3><a name="spatial_cell"></a>spatial_cell</h3>
3712<ul>
3713
3714<li>
3715
3716<p>Syntax:</p>
3717
3718<div>
3719<div>
3720<pre class="source">spatial_cell(point1, point2, x_increment, y_increment)
3721</pre></div></div>
3722</li>
3723<li>
3724
3725<p>Returns the grid cell that <tt>point1</tt> belongs to.</p>
3726</li>
3727<li>Arguments:
3728<ul>
3729
3730<li><tt>point1</tt> : a <tt>point</tt> representing the point of interest that its grid cell will be returned.</li>
3731<li><tt>point2</tt> : a <tt>point</tt> representing the origin of the grid.</li>
3732<li><tt>x_increment</tt> : a <tt>double</tt>, represents X increments.</li>
3733<li><tt>y_increment</tt> : a <tt>double</tt>, represents Y increments.</li>
3734</ul>
3735</li>
3736<li>Return Value:
3737<ul>
3738
3739<li>a <tt>rectangle</tt> representing the grid cell that <tt>point1</tt> belongs to,</li>
3740<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3741<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3742<li>a type error will be raised if:
3743<ul>
3744
3745<li>the first or second argument is any other non-point value,</li>
3746<li>or, the second or third argument is any other non-double value.</li>
3747</ul>
3748</li>
3749</ul>
3750</li>
3751<li>
3752
3753<p>Example:</p>
3754
3755<div>
3756<div>
3757<pre class="source">spatial_cell(point(&quot;39.28,70.48&quot;), create_point(20.0,50.0), 5.5, 6.0);
3758</pre></div></div>
3759</li>
3760<li>
3761
3762<p>The expected result is:</p>
3763
3764<div>
3765<div>
3766<pre class="source">rectangle(&quot;36.5,68.0 42.0,74.0&quot;);
3767</pre></div></div>
3768</li>
3769</ul><!--
3770 ! Licensed to the Apache Software Foundation (ASF) under one
3771 ! or more contributor license agreements. See the NOTICE file
3772 ! distributed with this work for additional information
3773 ! regarding copyright ownership. The ASF licenses this file
3774 ! to you under the Apache License, Version 2.0 (the
3775 ! "License"); you may not use this file except in compliance
3776 ! with the License. You may obtain a copy of the License at
3777 !
3778 ! http://www.apache.org/licenses/LICENSE-2.0
3779 !
3780 ! Unless required by applicable law or agreed to in writing,
3781 ! software distributed under the License is distributed on an
3782 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
3783 ! KIND, either express or implied. See the License for the
3784 ! specific language governing permissions and limitations
3785 ! under the License.
3786 !-->
3787</div></div>
3788<div class="section">
3789<h2><a name="Similarity_Functions"></a><a name="SimilarityFunctions" id="SimilarityFunctions">Similarity Functions</a></h2>
3790<p>AsterixDB supports queries with different similarity functions, including <a class="externalLink" href="http://en.wikipedia.org/wiki/Levenshtein_distance">edit distance</a> and <a class="externalLink" href="https://en.wikipedia.org/wiki/Jaccard_index">Jaccard</a>.</p>
3791<div class="section">
3792<h3><a name="edit_distance"></a>edit_distance</h3>
3793<ul>
3794
3795<li>
3796
3797<p>Syntax:</p>
3798
3799<div>
3800<div>
3801<pre class="source">edit_distance(expression1, expression2)
3802</pre></div></div>
3803</li>
3804<li>
3805
3806<p>Returns the edit distance of <tt>expression1</tt> and <tt>expression2</tt>.</p>
3807</li>
3808<li>Arguments:
3809<ul>
3810
3811<li><tt>expression1</tt> : a <tt>string</tt> or a homogeneous <tt>array</tt> of a comparable item type.</li>
3812<li><tt>expression2</tt> : The same type as <tt>expression1</tt>.</li>
3813</ul>
3814</li>
3815<li>Return Value:
3816<ul>
3817
3818<li>an <tt>bigint</tt> that represents the edit distance between <tt>expression1</tt> and <tt>expression2</tt>,</li>
3819<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3820<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3821<li>any other non-string input value will cause a type error.</li>
3822</ul>
3823</li>
3824<li>Note: an <a href="similarity.html#UsingIndexesToSupportSimilarityQueries">n_gram index</a> can be utilized for this function.</li>
3825<li>Example:
3826
3827<div>
3828<div>
3829<pre class="source">edit_distance(&quot;SuzannaTillson&quot;, &quot;Suzanna Tilson&quot;);
3830</pre></div></div>
3831</li>
3832<li>
3833
3834<p>The expected result is:</p>
3835
3836<div>
3837<div>
3838<pre class="source">2
3839</pre></div></div>
3840</li>
3841</ul></div>
3842<div class="section">
3843<h3><a name="edit_distance_check"></a>edit_distance_check</h3>
3844<ul>
3845
3846<li>
3847
3848<p>Syntax:</p>
3849
3850<div>
3851<div>
3852<pre class="source">edit_distance_check(expression1, expression2, threshold)
3853</pre></div></div>
3854</li>
3855<li>
3856
3857<p>Checks whether the edit distance of <tt>expression1</tt> and <tt>expression2</tt> is within a given threshold.</p>
3858</li>
3859<li>
3860
3861<p>Arguments:</p>
3862<ul>
3863
3864<li><tt>expression1</tt> : a <tt>string</tt> or a homogeneous <tt>array</tt> of a comparable item type.</li>
3865<li><tt>expression2</tt> : The same type as <tt>expression1</tt>.</li>
3866<li><tt>threshold</tt> : a <tt>bigint</tt> that represents the distance threshold.</li>
3867</ul>
3868</li>
3869<li>Return Value:
3870<ul>
3871
3872<li>an <tt>array</tt> with two items:
3873<ul>
3874
3875<li>The first item contains a <tt>boolean</tt> value representing whether the edit distance of <tt>expression1</tt> and <tt>expression2</tt> is within the given threshold.</li>
3876<li>The second item contains an <tt>integer</tt> that represents the edit distance of <tt>expression1</tt> and <tt>expression2</tt> if the first item is true.</li>
3877<li>If the first item is false, then the second item is set to 2147483647.</li>
3878</ul>
3879</li>
3880<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3881<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3882<li>a type error will be raised if:
3883<ul>
3884
3885<li>the first or second argument is any other non-string value,</li>
3886<li>or, the third argument is any other non-bigint value.</li>
3887</ul>
3888</li>
3889</ul>
3890</li>
3891<li>Note: an <a href="similarity.html#UsingIndexesToSupportSimilarityQueries">n_gram index</a> can be utilized for this function.</li>
3892<li>Example:
3893
3894<div>
3895<div>
3896<pre class="source">edit_distance_check(&quot;happy&quot;,&quot;hapr&quot;,2);
3897</pre></div></div>
3898</li>
3899<li>
3900
3901<p>The expected result is:</p>
3902
3903<div>
3904<div>
3905<pre class="source">[ true, 2 ]
3906</pre></div></div>
3907</li>
3908</ul></div>
3909<div class="section">
3910<h3><a name="edit_distance_contains"></a>edit_distance_contains</h3>
3911<ul>
3912
3913<li>
3914
3915<p>Syntax:</p>
3916
3917<div>
3918<div>
3919<pre class="source">edit_distance_contains(expression1, expression2, threshold)
3920</pre></div></div>
3921</li>
3922<li>
3923
3924<p>Checks whether <tt>expression1</tt> contains <tt>expression2</tt> with an <a class="externalLink" href="http://en.wikipedia.org/wiki/Levenshtein_distance">edit distance</a> within a given threshold.</p>
3925</li>
3926<li>
3927
3928<p>Arguments:</p>
3929<ul>
3930
3931<li><tt>expression1</tt> : a <tt>string</tt> or a homogeneous <tt>array</tt> of a comparable item type.</li>
3932<li><tt>expression2</tt> : The same type as <tt>expression1</tt>.</li>
3933<li><tt>threshold</tt> : a <tt>bigint</tt> that represents the distance threshold.</li>
3934</ul>
3935</li>
3936<li>Return Value:
3937<ul>
3938
3939<li>an <tt>array</tt> with two items:
3940<ul>
3941
3942<li>The first item contains a <tt>boolean</tt> value representing whether <tt>expression1</tt> can contain <tt>expression2</tt>.</li>
3943<li>The second item contains an <tt>integer</tt> that represents the required edit distance for <tt>expression1</tt> to contain <tt>expression2</tt> if the first item is true.</li>
3944</ul>
3945</li>
3946<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3947<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3948<li>a type error will be raised if:
3949<ul>
3950
3951<li>the first or second argument is any other non-string value,</li>
3952<li>or, the third argument is any other non-bigint value.</li>
3953</ul>
3954</li>
3955</ul>
3956</li>
3957<li>Note: an <a href="similarity.html#UsingIndexesToSupportSimilarityQueries">n_gram index</a> can be utilized for this function.</li>
3958<li>Example:
3959
3960<div>
3961<div>
3962<pre class="source">edit_distance_contains(&quot;happy&quot;,&quot;hapr&quot;,2);
3963</pre></div></div>
3964</li>
3965<li>
3966
3967<p>The expected result is:</p>
3968
3969<div>
3970<div>
3971<pre class="source">[ true, 1 ]
3972</pre></div></div>
3973</li>
3974</ul></div>
3975<div class="section">
3976<h3><a name="similarity_jaccard"></a>similarity_jaccard</h3>
3977<ul>
3978
3979<li>
3980
3981<p>Syntax:</p>
3982
3983<div>
3984<div>
3985<pre class="source">similarity_jaccard(array1, array2)
3986</pre></div></div>
3987</li>
3988<li>
3989
3990<p>Returns the <a class="externalLink" href="http://en.wikipedia.org/wiki/Jaccard_index">Jaccard similarity</a> of <tt>array1</tt> and <tt>array2</tt>.</p>
3991</li>
3992<li>Arguments:
3993<ul>
3994
3995<li><tt>array1</tt> : an <tt>array</tt> or <tt>multiset</tt>.</li>
3996<li><tt>array2</tt> : an <tt>array</tt> or <tt>multiset</tt>.</li>
3997</ul>
3998</li>
3999<li>Return Value:
4000<ul>
4001
4002<li>a <tt>float</tt> that represents the Jaccard similarity of <tt>array1</tt> and <tt>array2</tt>,</li>
4003<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
4004<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
4005<li><tt>missing</tt> if any element in any input array is <tt>missing</tt>,</li>
4006<li><tt>null</tt> if any element in any input array is <tt>null</tt> but no element in the input array is <tt>missing</tt>,</li>
4007<li>any other non-array input value or non-integer element in any input array will cause a type error.</li>
4008</ul>
4009</li>
4010<li>
4011
4012<p>Note: a <a href="similarity.html#UsingIndexesToSupportSimilarityQueries">keyword index</a> can be utilized for this function.</p>
4013</li>
4014<li>Example:
4015
4016<div>
4017<div>
4018<pre class="source">similarity_jaccard([1,5,8,9], [1,5,9,10]);
4019</pre></div></div>
4020</li>
4021<li>
4022
4023<p>The expected result is:</p>
4024
4025<div>
4026<div>
4027<pre class="source">0.6
4028</pre></div></div>
4029</li>
4030</ul></div>
4031<div class="section">
4032<h3><a name="similarity_jaccard_check"></a>similarity_jaccard_check</h3>
4033<ul>
4034
4035<li>
4036
4037<p>Syntax:</p>
4038
4039<div>
4040<div>
4041<pre class="source">similarity_jaccard_check(array1, array2, threshold)
4042</pre></div></div>
4043</li>
4044<li>
4045
4046<p>Checks whether <tt>array1</tt> and <tt>array2</tt> have a <a class="externalLink" href="http://en.wikipedia.org/wiki/Jaccard_index">Jaccard similarity</a> greater than or equal to threshold. Again, the &#x201c;check&#x201d; version of Jaccard is faster than the &#x201c;non_check&#x201d; version.</p>
4047</li>
4048<li>
4049
4050<p>Arguments:</p>
4051<ul>
4052
4053<li><tt>array1</tt> : an <tt>array</tt> or <tt>multiset</tt>.</li>
4054<li><tt>array2</tt> : an <tt>array</tt> or <tt>multiset</tt>.</li>
4055<li><tt>threshold</tt> : a <tt>double</tt> that represents the similarity threshold.</li>
4056</ul>
4057</li>
4058<li>Return Value:
4059<ul>
4060
4061<li>an <tt>array</tt> with two items:
4062<ul>
4063
4064<li>The first item contains a <tt>boolean</tt> value representing whether <tt>array1</tt> and <tt>array2</tt> are similar.</li>
4065<li>The second item contains a <tt>float</tt> that represents the Jaccard similarity of <tt>array1</tt> and <tt>array2</tt> if it is greater than or equal to the threshold, or 0 otherwise.</li>
4066</ul>
4067</li>
4068<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
4069<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
4070<li><tt>missing</tt> if any element in any input array is <tt>missing</tt>,</li>
4071<li><tt>null</tt> if any element in any input array is <tt>null</tt> but no element in the input array is <tt>missing</tt>,</li>
4072<li>a type error will be raised if:
4073<ul>
4074
4075<li>the first or second argument is any other non-array value,
4076<ul>
4077
4078<li>or, the third argument is any other non-double value.</li>
4079</ul>
4080</li>
4081</ul>
4082</li>
4083</ul>
4084</li>
4085<li>
4086
4087<p>Note: a <a href="similarity.html#UsingIndexesToSupportSimilarityQueries">keyword index</a> can be utilized for this function.</p>
4088</li>
4089<li>Example:
4090
4091<div>
4092<div>
4093<pre class="source">similarity_jaccard_check([1,5,8,9], [1,5,9,10], 0.6);
4094</pre></div></div>
4095</li>
4096<li>
4097
4098<p>The expected result is:</p>
4099
4100<div>
4101<div>
4102<pre class="source">[ false, 0.0 ]
4103</pre></div></div>
4104</li>
4105</ul><!--
4106 ! Licensed to the Apache Software Foundation (ASF) under one
4107 ! or more contributor license agreements. See the NOTICE file
4108 ! distributed with this work for additional information
4109 ! regarding copyright ownership. The ASF licenses this file
4110 ! to you under the Apache License, Version 2.0 (the
4111 ! "License"); you may not use this file except in compliance
4112 ! with the License. You may obtain a copy of the License at
4113 !
4114 ! http://www.apache.org/licenses/LICENSE-2.0
4115 !
4116 ! Unless required by applicable law or agreed to in writing,
4117 ! software distributed under the License is distributed on an
4118 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
4119 ! KIND, either express or implied. See the License for the
4120 ! specific language governing permissions and limitations
4121 ! under the License.
4122 !-->
4123</div></div>
4124<div class="section">
4125<h2><a name="Tokenizing_Functions"></a><a name="TokenizingFunctions" id="TokenizingFunctions">Tokenizing Functions</a></h2>
4126<div class="section">
4127<h3><a name="word_tokens"></a>word_tokens</h3>
4128<ul>
4129
4130<li>
4131
4132<p>Syntax:</p>
4133
4134<div>
4135<div>
4136<pre class="source">word_tokens(string)
4137</pre></div></div>
4138</li>
4139<li>
4140
4141<p>Returns an array of word tokens of <tt>string</tt> using non_alphanumeric characters as delimiters.</p>
4142</li>
4143<li>Arguments:
4144<ul>
4145
4146<li><tt>string</tt> : a <tt>string</tt> that will be tokenized.</li>
4147</ul>
4148</li>
4149<li>Return Value:
4150<ul>
4151
4152<li>an <tt>array</tt> of <tt>string</tt> word tokens,</li>
4153<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
4154<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
4155<li>any other non-string input value will cause a type error.</li>
4156</ul>
4157</li>
4158<li>
4159
4160<p>Example:</p>
4161
4162<div>
4163<div>
4164<pre class="source">word_tokens(&quot;I like the phone, awesome!&quot;);
4165</pre></div></div>
4166</li>
4167<li>
4168
4169<p>The expected result is:</p>
4170
4171<div>
4172<div>
4173<pre class="source">[ &quot;i&quot;, &quot;like&quot;, &quot;the&quot;, &quot;phone&quot;, &quot;awesome&quot; ]
4174</pre></div></div>
4175</li>
4176</ul><!--
4177 ! Licensed to the Apache Software Foundation (ASF) under one
4178 ! or more contributor license agreements. See the NOTICE file
4179 ! distributed with this work for additional information
4180 ! regarding copyright ownership. The ASF licenses this file
4181 ! to you under the Apache License, Version 2.0 (the
4182 ! "License"); you may not use this file except in compliance
4183 ! with the License. You may obtain a copy of the License at
4184 !
4185 ! http://www.apache.org/licenses/LICENSE-2.0
4186 !
4187 ! Unless required by applicable law or agreed to in writing,
4188 ! software distributed under the License is distributed on an
4189 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
4190 ! KIND, either express or implied. See the License for the
4191 ! specific language governing permissions and limitations
4192 ! under the License.
4193 !-->
4194</div></div>
4195<div class="section">
4196<h2><a name="Temporal_Functions"></a><a name="TemporalFunctions" id="TemporalFunctions">Temporal Functions</a></h2>
4197<div class="section">
4198<h3><a name="get_year.2Fget_month.2Fget_day.2Fget_hour.2Fget_minute.2Fget_second.2Fget_millisecond"></a>get_year/get_month/get_day/get_hour/get_minute/get_second/get_millisecond</h3>
4199<ul>
4200
4201<li>
4202
4203<p>Syntax:</p>
4204
4205<div>
4206<div>
4207<pre class="source">get_year/get_month/get_day/get_hour/get_minute/get_second/get_millisecond(temporal_value)
4208</pre></div></div>
4209</li>
4210<li>
4211
4212<p>Accessors for accessing fields in a temporal value</p>
4213</li>
4214<li>Arguments:
4215<ul>
4216
4217<li><tt>temporal_value</tt> : a temporal value represented as one of the following types: <tt>date</tt>, <tt>datetime</tt>, <tt>time</tt>, and <tt>duration</tt>.</li>
4218</ul>
4219</li>
4220<li>Return Value:
4221<ul>
4222
4223<li>an <tt>bigint</tt> value representing the field to be extracted,</li>
4224<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
4225<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
4226<li>any other non-interval input value will cause a type error.</li>
4227</ul>
4228</li>
4229<li>
4230
4231<p>Example:</p>
4232
4233<div>
4234<div>
4235<pre class="source">{
4236 &quot;year&quot;: get_year(date(&quot;2010-10-30&quot;)),
4237 &quot;month&quot;: get_month(datetime(&quot;1987-11-19T23:49:23.938&quot;)),
4238 &quot;day&quot;: get_day(date(&quot;2010-10-30&quot;)),
4239 &quot;hour&quot;: get_hour(time(&quot;12:23:34.930+07:00&quot;)),
4240 &quot;min&quot;: get_minute(duration(&quot;P3Y73M632DT49H743M3948.94S&quot;)),
4241 &quot;second&quot;: get_second(datetime(&quot;1987-11-19T23:49:23.938&quot;)),
4242 &quot;ms&quot;: get_millisecond(duration(&quot;P3Y73M632DT49H743M3948.94S&quot;))
4243};
4244</pre></div></div>
4245</li>
4246<li>
4247
4248<p>The expected result is:</p>
4249
4250<div>
4251<div>
4252<pre class="source">{ &quot;year&quot;: 2010, &quot;month&quot;: 11, &quot;day&quot;: 30, &quot;hour&quot;: 5, &quot;min&quot;: 28, &quot;second&quot;: 23, &quot;ms&quot;: 94 }
4253</pre></div></div>
4254</li>
4255</ul></div>
4256<div class="section">
4257<h3><a name="adjust_datetime_for_timezone"></a>adjust_datetime_for_timezone</h3>
4258<ul>
4259
4260<li>
4261
4262<p>Syntax:</p>
4263
4264<div>
4265<div>
4266<pre class="source">adjust_datetime_for_timezone(datetime, string)
4267</pre></div></div>
4268</li>
4269<li>
4270
4271<p>Adjusts the given datetime <tt>datetime</tt> by applying the timezone information <tt>string</tt>.</p>
4272</li>
4273<li>Arguments:
4274<ul>
4275
4276<li><tt>datetime</tt> : a <tt>datetime</tt> value to be adjusted.</li>
4277<li><tt>string</tt> : a <tt>string</tt> representing the timezone information.</li>
4278</ul>
4279</li>
4280<li>Return Value:
4281<ul>
4282
4283<li>a <tt>string</tt> value representing the new datetime after being adjusted by the timezone information,</li>
4284<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
4285<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
4286<li>a type error will be raised if:
4287<ul>
4288
4289<li>the first argument is any other non-datetime value,</li>
4290<li>or, the second argument is any other non-string value.</li>
4291</ul>
4292</li>
4293</ul>
4294</li>
4295<li>
4296
4297<p>Example:</p>
4298
4299<div>
4300<div>
4301<pre class="source">adjust_datetime_for_timezone(datetime(&quot;2008-04-26T10:10:00&quot;), &quot;+08:00&quot;);
4302</pre></div></div>
4303</li>
4304<li>
4305
4306<p>The expected result is:</p>
4307
4308<div>
4309<div>
4310<pre class="source">&quot;2008-04-26T18:10:00.000+08:00&quot;
4311</pre></div></div>
4312</li>
4313</ul></div>
4314<div class="section">
4315<h3><a name="adjust_time_for_timezone"></a>adjust_time_for_timezone</h3>
4316<ul>
4317
4318<li>
4319
4320<p>Syntax:</p>
4321
4322<div>
4323<div>
4324<pre class="source">adjust_time_for_timezone(time, string)
4325</pre></div></div>
4326</li>
4327<li>
4328
4329<p>Adjusts the given time <tt>time</tt> by applying the timezone information <tt>string</tt>.</p>
4330</li>
4331<li>Arguments:
4332<ul>
4333
4334<li><tt>time</tt> : a <tt>time</tt> value to be adjusted.</li>
4335<li><tt>string</tt> : a <tt>string</tt> representing the timezone information.</li>
4336</ul>
4337</li>
4338<li>Return Value:
4339<ul>
4340
4341<li>a <tt>string</tt> value representing the new time after being adjusted by the timezone information,</li>
4342<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
4343<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
4344<li>a type error will be raised if:
4345<ul>
4346
4347<li>the first argument is any other non-time value,</li>
4348<li>or, the second argument is any other non-string value.</li>
4349</ul>
4350</li>
4351</ul>
4352</li>
4353<li>
4354
4355<p>Example:</p>
4356
4357<div>
4358<div>
4359<pre class="source">adjust_time_for_timezone(get_time_from_datetime(datetime(&quot;2008-04-26T10:10:00&quot;)), &quot;+08:00&quot;);
4360</pre></div></div>
4361</li>
4362<li>
4363
4364<p>The expected result is:</p>
4365
4366<div>
4367<div>
4368<pre class="source">&quot;18:10:00.000+08:00&quot;
4369</pre></div></div>
4370</li>
4371</ul></div>
4372<div class="section">
4373<h3><a name="calendar_duration_from_datetime"></a>calendar_duration_from_datetime</h3>
4374<ul>
4375
4376<li>
4377
4378<p>Syntax:</p>
4379
4380<div>
4381<div>
4382<pre class="source">calendar_duration_from_datetime(datetime, duration_value)
4383</pre></div></div>
4384</li>
4385<li>
4386
4387<p>Gets a user_friendly representation of the duration <tt>duration_value</tt> based on the given datetime <tt>datetime</tt>.</p>
4388</li>
4389<li>Arguments:
4390<ul>
4391
4392<li><tt>datetime</tt> : a <tt>datetime</tt> value to be used as the reference time point.</li>
4393<li><tt>duration_value</tt> : a <tt>duration</tt> value to be converted.</li>
4394</ul>
4395</li>
4396<li>Return Value:
4397<ul>
4398
4399<li>a <tt>duration</tt> value with the duration as <tt>duration_value</tt> but with a user_friendly representation,</li>
4400<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
4401<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
4402<li>a type error will be raised if:
4403<ul>
4404
4405<li>the first argument is any other non-datetime value,</li>
4406<li>or, the second argument is any other non-duration input value.</li>
4407</ul>
4408</li>
4409</ul>
4410</li>
4411<li>
4412
4413<p>Example:</p>
4414
4415<div>
4416<div>
4417<pre class="source">calendar_duration_from_datetime(
4418 datetime(&quot;2016-03-26T10:10:00&quot;),
4419 datetime(&quot;2016-03-26T10:10:00&quot;) - datetime(&quot;2011-01-01T00:00:00&quot;)
4420);
4421</pre></div></div>
4422</li>
4423<li>
4424
4425<p>The expected result is:</p>
4426
4427<div>
4428<div>
4429<pre class="source">duration(&quot;P5Y2M24DT10H10M&quot;)
4430</pre></div></div>
4431</li>
4432</ul></div>
4433<div class="section">
4434<h3><a name="get_year_month_duration.2Fget_day_time_duration"></a>get_year_month_duration/get_day_time_duration</h3>
4435<ul>
4436
4437<li>
4438
4439<p>Syntax:</p>
4440
4441<div>
4442<div>
4443<pre class="source">get_year_month_duration/get_day_time_duration(duration_value)
4444</pre></div></div>
4445</li>
4446<li>
4447
4448<p>Extracts the correct <tt>duration</tt> subtype from <tt>duration_value</tt>.</p>
4449</li>
4450<li>Arguments:
4451<ul>
4452
4453<li><tt>duration_value</tt> : a <tt>duration</tt> value to be converted.</li>
4454</ul>
4455</li>
4456<li>Return Value:
4457<ul>
4458
4459<li>a <tt>year_month_duration</tt> value or a <tt>day_time_duration</tt> value,</li>
4460<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
4461<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
4462<li>any other non-duration input value will cause a type error.</li>
4463</ul>
4464</li>
4465<li>
4466
4467<p>Example:</p>
4468
4469<div>
4470<div>
4471<pre class="source">get_year_month_duration(duration(&quot;P12M50DT10H&quot;));
4472</pre></div></div>
4473</li>
4474<li>
4475
4476<p>The expected result is:</p>
4477
4478<div>
4479<div>
4480<pre class="source">year_month_duration(&quot;P1Y&quot;)
4481</pre></div></div>
4482</li>
4483</ul></div>
4484<div class="section">
4485<h3><a name="months_from_year_month_duration.2Fmilliseconds_from_day_time_duration"></a>months_from_year_month_duration/milliseconds_from_day_time_duration</h3>
4486<ul>
4487
4488<li>
4489
4490<p>Syntax:</p>
4491
4492<div>
4493<div>
4494<pre class="source">months_from_year_month_duration/milliseconds_from_day_time_duration(duration_value)
4495</pre></div></div>
4496</li>
4497<li>
4498
4499<p>Extracts the number of months or the number of milliseconds from the <tt>duration</tt> subtype.</p>
4500</li>
4501<li>Arguments:
4502<ul>
4503
4504<li><tt>duration_value</tt> : a <tt>duration</tt> of the correct subtype.</li>
4505</ul>
4506</li>
4507<li>Return Value:
4508<ul>
4509
4510<li>an <tt>bigint</tt> representing the number or months/milliseconds,</li>
4511<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
4512<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
4513<li>any other non-duration input value will cause a type error.</li>
4514</ul>
4515</li>
4516<li>
4517
4518<p>Example:</p>
4519
4520<div>
4521<div>
4522<pre class="source">months_from_year_month_duration(get_year_month_duration(duration(&quot;P5Y7MT50M&quot;)));
4523</pre></div></div>
4524</li>
4525<li>
4526
4527<p>The expected result is:</p>
4528
4529<div>
4530<div>
4531<pre class="source">67
4532</pre></div></div>
4533</li>
4534</ul></div>
4535<div class="section">
4536<h3><a name="duration_from_months.2Fduration_from_ms"></a>duration_from_months/duration_from_ms</h3>
4537<ul>
4538
4539<li>
4540
4541<p>Syntax:</p>
4542
4543<div>
4544<div>
4545<pre class="source">duration_from_months/duration_from_ms(number_value)
4546</pre></div></div>
4547</li>
4548<li>
4549
4550<p>Creates a <tt>duration</tt> from <tt>number_value</tt>.</p>
4551</li>
4552<li>Arguments:
4553<ul>
4554
4555<li><tt>number_value</tt> : a <tt>bigint</tt> representing the number of months/milliseconds</li>
4556</ul>
4557</li>
4558<li>Return Value:
4559<ul>
4560
4561<li>a <tt>duration</tt> containing <tt>number_value</tt> value for months/milliseconds,</li>
4562<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
4563<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
4564<li>any other non-duration input value will cause a type error.</li>
4565</ul>
4566</li>
4567<li>
4568
4569<p>Example:</p>
4570
4571<div>
4572<div>
4573<pre class="source">duration_from_months(8);
4574</pre></div></div>
4575</li>
4576<li>
4577
4578<p>The expected result is:</p>
4579
4580<div>
4581<div>
4582<pre class="source">duration(&quot;P8M&quot;)
4583</pre></div></div>
4584</li>
4585</ul></div>
4586<div class="section">
4587<h3><a name="duration_from_interval"></a>duration_from_interval</h3>
4588<ul>
4589
4590<li>
4591
4592<p>Syntax:</p>
4593
4594<div>
4595<div>
4596<pre class="source">duration_from_interval(interval_value)
4597</pre></div></div>
4598</li>
4599<li>
4600
4601<p>Creates a <tt>duration</tt> from <tt>interval_value</tt>.</p>
4602</li>
4603<li>Arguments:
4604<ul>
4605
4606<li><tt>interval_value</tt> : an <tt>interval</tt> value</li>
4607</ul>
4608</li>
4609<li>Return Value:
4610<ul>
4611
4612<li>a <tt>duration</tt> representing the time in the <tt>interval_value</tt></li>
4613<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
4614<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
4615<li>any other non-duration input value will cause a type error.</li>
4616</ul>
4617</li>
4618<li>
4619
4620<p>Example:</p>
4621
4622<div>
4623<div>
4624<pre class="source">{
4625 &quot;dr1&quot; : duration_from_interval(interval(date(&quot;2010-10-30&quot;), date(&quot;2010-12-21&quot;))),
4626 &quot;dr2&quot; : duration_from_interval(interval(datetime(&quot;2012-06-26T01:01:01.111&quot;), datetime(&quot;2012-07-27T02:02:02.222&quot;))),
4627 &quot;dr3&quot; : duration_from_interval(interval(time(&quot;12:32:38&quot;), time(&quot;20:29:20&quot;))),
4628 &quot;dr4&quot; : duration_from_interval(null)
4629};
4630</pre></div></div>
4631</li>
4632<li>
4633
4634<p>The expected result is:</p>
4635
4636<div>
4637<div>
4638<pre class="source">{
4639 &quot;dr1&quot;: day_time_duration(&quot;P52D&quot;),
4640 &quot;dr2&quot;: day_time_duration(&quot;P31DT1H1M1.111S&quot;),
4641 &quot;dr3&quot;: day_time_duration(&quot;PT7H56M42S&quot;),
4642 &quot;dr4&quot;: null
4643}
4644</pre></div></div>
4645</li>
4646</ul></div>
4647<div class="section">
4648<h3><a name="current_date"></a>current_date</h3>
4649<ul>
4650
4651<li>
4652
4653<p>Syntax:</p>
4654
4655<div>
4656<div>
4657<pre class="source">current_date()
4658</pre></div></div>
4659</li>
4660<li>
4661
4662<p>Gets the current date.</p>
4663</li>
4664<li>Arguments: None</li>
4665<li>Return Value:
4666<ul>
4667
4668<li>a <tt>date</tt> value of the date when the function is called.</li>
4669</ul>
4670</li>
4671</ul></div>
4672<div class="section">
4673<h3><a name="current_time"></a>current_time</h3>
4674<ul>
4675
4676<li>
4677
4678<p>Syntax:</p>
4679
4680<div>
4681<div>
4682<pre class="source">current_time()
4683</pre></div></div>
4684</li>
4685<li>
4686
4687<p>Get the current time</p>
4688</li>
4689<li>Arguments: None</li>
4690<li>Return Value:
4691<ul>
4692
4693<li>a <tt>time</tt> value of the time when the function is called.</li>
4694</ul>
4695</li>
4696</ul></div>
4697<div class="section">
4698<h3><a name="current_datetime"></a>current_datetime</h3>
4699<ul>
4700
4701<li>
4702
4703<p>Syntax:</p>
4704
4705<div>
4706<div>
4707<pre class="source">current_datetime()
4708</pre></div></div>
4709</li>
4710<li>
4711
4712<p>Get the current datetime</p>
4713</li>
4714<li>Arguments: None</li>
4715<li>Return Value:
4716<ul>
4717
4718<li>a <tt>datetime</tt> value of the datetime when the function is called.</li>
4719</ul>
4720</li>
4721</ul></div>
4722<div class="section">
4723<h3><a name="get_date_from_datetime"></a>get_date_from_datetime</h3>
4724<ul>
4725
4726<li>
4727
4728<p>Syntax:</p>
4729
4730<div>
4731<div>
4732<pre class="source">get_date_from_datetime(datetime)
4733</pre></div></div>
4734</li>
4735<li>
4736
4737<p>Gets the date value from the given datetime value <tt>datetime</tt>.</p>
4738</li>
4739<li>Arguments:
4740<ul>
4741
4742<li><tt>datetime</tt>: a <tt>datetime</tt> value to be extracted from.</li>
4743</ul>
4744</li>
4745<li>Return Value:
4746<ul>
4747
4748<li>a <tt>date</tt> value from the datetime,</li>
4749<li>any other non-datetime input value will cause a type error.</li>
4750</ul>
4751</li>
4752</ul></div>
4753<div class="section">
4754<h3><a name="get_time_from_datetime"></a>get_time_from_datetime</h3>
4755<ul>
4756
4757<li>
4758
4759<p>Syntax:</p>
4760
4761<div>
4762<div>
4763<pre class="source">get_time_from_datetime(datetime)
4764</pre></div></div>
4765</li>
4766<li>
4767
4768<p>Get the time value from the given datetime value <tt>datetime</tt></p>
4769</li>
4770<li>Arguments:
4771<ul>
4772
4773<li><tt>datetime</tt>: a <tt>datetime</tt> value to be extracted from.</li>
4774</ul>
4775</li>
4776<li>Return Value:
4777<ul>
4778
4779<li>a <tt>time</tt> value from the datetime.</li>
4780<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
4781<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
4782<li>any other non-datetime input value will cause a type error.</li>
4783</ul>
4784</li>
4785<li>
4786
4787<p>Example:</p>
4788
4789<div>
4790<div>
4791<pre class="source">get_time_from_datetime(datetime(&quot;2016-03-26T10:10:00&quot;));
4792</pre></div></div>
4793</li>
4794<li>
4795
4796<p>The expected result is:</p>
4797
4798<div>
4799<div>
4800<pre class="source">time(&quot;10:10:00.000Z&quot;)
4801</pre></div></div>
4802</li>
4803</ul></div>
4804<div class="section">
4805<h3><a name="day_of_week"></a>day_of_week</h3>
4806<ul>
4807
4808<li>
4809
4810<p>Syntax:</p>
4811
4812<div>
4813<div>
4814<pre class="source">day_of_week(date)
4815</pre></div></div>
4816</li>
4817<li>
4818
4819<p>Finds the day of the week for a given date (1_7)</p>
4820</li>
4821<li>Arguments:
4822<ul>
4823
4824<li><tt>date</tt>: a <tt>date</tt> value (Can also be a <tt>datetime</tt>)</li>
4825</ul>
4826</li>
4827<li>Return Value:
4828<ul>
4829
4830<li>an <tt>tinyint</tt> representing the day of the week (1_7),</li>
4831<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
4832<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
4833<li>any other non-date input value will cause a type error.</li>
4834</ul>
4835</li>
4836<li>
4837
4838<p>Example:</p>
4839
4840<div>
4841<div>
4842<pre class="source">day_of_week(datetime(&quot;2012-12-30T12:12:12.039Z&quot;));
4843</pre></div></div>
4844</li>
4845<li>
4846
4847<p>The expected result is:</p>
4848
4849<div>
4850<div>
4851<pre class="source">7
4852</pre></div></div>
4853</li>
4854</ul></div>
4855<div class="section">
4856<h3><a name="date_from_unix_time_in_days"></a>date_from_unix_time_in_days</h3>
4857<ul>
4858
4859<li>
4860
4861<p>Syntax:</p>
4862
4863<div>
4864<div>
4865<pre class="source">date_from_unix_time_in_days(numeric_value)
4866</pre></div></div>
4867</li>
4868<li>
4869
4870<p>Gets a date representing the time after <tt>numeric_value</tt> days since 1970_01_01.</p>
4871</li>
4872<li>Arguments:
4873<ul>
4874
4875<li><tt>numeric_value</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt> value representing the number of days.</li>
4876</ul>
4877</li>
4878<li>Return Value:
4879<ul>
4880
4881<li>a <tt>date</tt> value as the time after <tt>numeric_value</tt> days since 1970-01-01,</li>
4882<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
4883<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
4884<li>any other non-numeric input value will cause a type error.</li>
4885</ul>
4886</li>
4887</ul></div>
4888<div class="section">
4889<h3><a name="datetime_from_unix_time_in_ms"></a>datetime_from_unix_time_in_ms</h3>
4890<ul>
4891
4892<li>
4893
4894<p>Syntax:</p>
4895
4896<div>
4897<div>
4898<pre class="source">datetime_from_unix_time_in_ms(numeric_value)
4899</pre></div></div>
4900</li>
4901<li>
4902
4903<p>Gets a datetime representing the time after <tt>numeric_value</tt> milliseconds since 1970_01_01T00:00:00Z.</p>
4904</li>
4905<li>Arguments:
4906<ul>
4907
4908<li><tt>numeric_value</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt> value representing the number of milliseconds.</li>
4909</ul>
4910</li>
4911<li>Return Value:
4912<ul>
4913
4914<li>a <tt>datetime</tt> value as the time after <tt>numeric_value</tt> milliseconds since 1970-01-01T00:00:00Z,</li>
4915<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
4916<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
4917<li>any other non-numeric input value will cause a type error.</li>
4918</ul>
4919</li>
4920</ul></div>
4921<div class="section">
4922<h3><a name="datetime_from_unix_time_in_secs"></a>datetime_from_unix_time_in_secs</h3>
4923<ul>
4924
4925<li>
4926
4927<p>Syntax:</p>
4928
4929<div>
4930<div>
4931<pre class="source">datetime_from_unix_time_in_secs(numeric_value)
4932</pre></div></div>
4933</li>
4934<li>
4935
4936<p>Gets a datetime representing the time after <tt>numeric_value</tt> seconds since 1970_01_01T00:00:00Z.</p>
4937</li>
4938<li>Arguments:
4939<ul>
4940
4941<li><tt>numeric_value</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt> value representing the number of seconds.</li>
4942</ul>
4943</li>
4944<li>Return Value:
4945<ul>
4946
4947<li>a <tt>datetime</tt> value as the time after <tt>numeric_value</tt> seconds since 1970_01_01T00:00:00Z,</li>
4948<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
4949<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
4950<li>any other non-numeric input value will cause a type error.</li>
4951</ul>
4952</li>
4953</ul></div>
4954<div class="section">
4955<h3><a name="datetime_from_date_time"></a>datetime_from_date_time</h3>
4956<ul>
4957
4958<li>Syntax:</li>
4959</ul>
4960<p>datetime_from_date_time(date,time)</p>
4961<ul>
4962
4963<li>Gets a datetime representing the combination of <tt>date</tt> and <tt>time</tt>
4964<ul>
4965
4966<li>Arguments:</li>
4967<li><tt>date</tt>: a <tt>date</tt> value</li>
4968<li><tt>time</tt> a <tt>time</tt> value</li>
4969</ul>
4970</li>
4971<li>Return Value:
4972<ul>
4973
4974<li>a <tt>datetime</tt> value by combining <tt>date</tt> and <tt>time</tt>,</li>
4975<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
4976<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
4977<li>a type error will be raised if
4978<ul>
4979
4980<li>the first argument is any other non-date value,</li>
4981<li>or, the second argument is any other non-time value.</li>
4982</ul>
4983</li>
4984</ul>
4985</li>
4986</ul></div>
4987<div class="section">
4988<h3><a name="time_from_unix_time_in_ms"></a>time_from_unix_time_in_ms</h3>
4989<ul>
4990
4991<li>
4992
4993<p>Syntax:</p>
4994
4995<div>
4996<div>
4997<pre class="source">time_from_unix_time_in_ms(numeric_value)
4998</pre></div></div>
4999</li>
5000<li>
5001
5002<p>Gets a time representing the time after <tt>numeric_value</tt> milliseconds since 00:00:00.000Z.</p>
5003</li>
5004<li>Arguments:
5005<ul>
5006
5007<li><tt>numeric_value</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt> value representing the number of milliseconds.</li>
5008</ul>
5009</li>
5010<li>Return Value:
5011<ul>
5012
5013<li>a <tt>time</tt> value as the time after <tt>numeric_value</tt> milliseconds since 00:00:00.000Z,</li>
5014<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5015<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5016<li>any other non-numeric input value will cause a type error.</li>
5017</ul>
5018</li>
5019<li>
5020
5021<p>Example:</p>
5022
5023<div>
5024<div>
5025<pre class="source">{
5026 &quot;date&quot;: date_from_unix_time_in_days(15800),
5027 &quot;datetime&quot;: datetime_from_unix_time_in_ms(1365139700000),
5028 &quot;time&quot;: time_from_unix_time_in_ms(3748)
5029};
5030</pre></div></div>
5031</li>
5032<li>
5033
5034<p>The expected result is:</p>
5035
5036<div>
5037<div>
5038<pre class="source">{ &quot;date&quot;: date(&quot;2013-04-05&quot;), &quot;datetime&quot;: datetime(&quot;2013-04-05T05:28:20.000Z&quot;), &quot;time&quot;: time(&quot;00:00:03.748Z&quot;) }
5039</pre></div></div>
5040</li>
5041</ul></div>
5042<div class="section">
5043<h3><a name="unix_time_from_date_in_days"></a>unix_time_from_date_in_days</h3>
5044<ul>
5045
5046<li>
5047
5048<p>Syntax:</p>
5049
5050<div>
5051<div>
5052<pre class="source">unix_time_from_date_in_days(date_value)
5053</pre></div></div>
5054</li>
5055<li>
5056
5057<p>Gets an integer value representing the number of days since 1970_01_01 for <tt>date_value</tt>.</p>
5058</li>
5059<li>Arguments:
5060<ul>
5061
5062<li><tt>date_value</tt>: a <tt>date</tt> value.</li>
5063</ul>
5064</li>
5065<li>Return Value:
5066<ul>
5067
5068<li>a <tt>bigint</tt> value representing the number of days,</li>
5069<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5070<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5071<li>any other non-date input value will cause a type error.</li>
5072</ul>
5073</li>
5074</ul></div>
5075<div class="section">
5076<h3><a name="unix_time_from_datetime_in_ms"></a>unix_time_from_datetime_in_ms</h3>
5077<ul>
5078
5079<li>
5080
5081<p>Syntax:</p>
5082
5083<div>
5084<div>
5085<pre class="source">unix_time_from_datetime_in_ms(datetime_value)
5086</pre></div></div>
5087</li>
5088<li>
5089
5090<p>Gets an integer value representing the time in milliseconds since 1970_01_01T00:00:00Z for <tt>datetime_value</tt>.</p>
5091</li>
5092<li>Arguments:
5093<ul>
5094
5095<li><tt>datetime_value</tt> : a <tt>datetime</tt> value.</li>
5096</ul>
5097</li>
5098<li>Return Value:
5099<ul>
5100
5101<li>a <tt>bigint</tt> value representing the number of milliseconds,</li>
5102<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5103<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5104<li>any other non-datetime input value will cause a type error.</li>
5105</ul>
5106</li>
5107</ul></div>
5108<div class="section">
5109<h3><a name="unix_time_from_datetime_in_secs"></a>unix_time_from_datetime_in_secs</h3>
5110<ul>
5111
5112<li>
5113
5114<p>Syntax:</p>
5115
5116<div>
5117<div>
5118<pre class="source">unix_time_from_datetime_in_secs(datetime_value)
5119</pre></div></div>
5120</li>
5121<li>
5122
5123<p>Gets an integer value representing the time in seconds since 1970_01_01T00:00:00Z for <tt>datetime_value</tt>.</p>
5124</li>
5125<li>Arguments:
5126<ul>
5127
5128<li><tt>datetime_value</tt> : a <tt>datetime</tt> value.</li>
5129</ul>
5130</li>
5131<li>Return Value:
5132<ul>
5133
5134<li>a <tt>bigint</tt> value representing the number of seconds,</li>
5135<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5136<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5137<li>any other non-datetime input value will cause a type error.</li>
5138</ul>
5139</li>
5140</ul></div>
5141<div class="section">
5142<h3><a name="unix_time_from_time_in_ms"></a>unix_time_from_time_in_ms</h3>
5143<ul>
5144
5145<li>
5146
5147<p>Syntax:</p>
5148
5149<div>
5150<div>
5151<pre class="source">unix_time_from_time_in_ms(time_value)
5152</pre></div></div>
5153</li>
5154<li>
5155
5156<p>Gets an integer value representing the time the milliseconds since 00:00:00.000Z for <tt>time_value</tt>.</p>
5157</li>
5158<li>Arguments:
5159<ul>
5160
5161<li><tt>time_value</tt> : a <tt>time</tt> value.</li>
5162</ul>
5163</li>
5164<li>Return Value:
5165<ul>
5166
5167<li>a <tt>bigint</tt> value representing the number of milliseconds,</li>
5168<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5169<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5170<li>any other non-datetime input value will cause a type error.</li>
5171</ul>
5172</li>
5173<li>
5174
5175<p>Example:</p>
5176
5177<div>
5178<div>
5179<pre class="source">{
5180 &quot;date&quot;: date_from_unix_time_in_days(15800),
5181 &quot;datetime&quot;: datetime_from_unix_time_in_ms(1365139700000),
5182 &quot;time&quot;: time_from_unix_time_in_ms(3748)
5183}
5184</pre></div></div>
5185</li>
5186<li>
5187
5188<p>The expected result is:</p>
5189
5190<div>
5191<div>
5192<pre class="source">{ &quot;date&quot;: date(&quot;2013-04-05&quot;), &quot;datetime&quot;: datetime(&quot;2013-04-05T05:28:20.000Z&quot;), &quot;time&quot;: time(&quot;00:00:03.748Z&quot;) }
5193</pre></div></div>
5194</li>
5195</ul></div>
5196<div class="section">
5197<h3><a name="parse_date.2Fparse_time.2Fparse_datetime"></a>parse_date/parse_time/parse_datetime</h3>
5198<ul>
5199
5200<li>Syntax:</li>
5201</ul>
5202<p>parse_date/parse_time/parse_datetime(date,formatting_expression)</p>
5203<ul>
5204
5205<li>Creates a <tt>date/time/date_time</tt> value by treating <tt>date</tt> with formatting <tt>formatting_expression</tt></li>
5206<li>Arguments:
5207<ul>
5208
5209<li><tt>date</tt>: a <tt>string</tt> value representing the <tt>date/time/datetime</tt>.</li>
5210<li><tt>formatting_expression</tt> a <tt>string</tt> value providing the formatting for <tt>date_expression</tt>.Characters used to create date expression:</li>
5211<li><tt>h</tt> hours</li>
5212<li><tt>m</tt> minutes</li>
5213<li><tt>s</tt> seconds</li>
5214<li><tt>n</tt> milliseconds</li>
5215<li><tt>a</tt> am/pm</li>
5216<li><tt>z</tt> timezone</li>
5217<li><tt>Y</tt> year</li>
5218<li><tt>M</tt> month</li>
5219<li><tt>D</tt> day</li>
5220<li><tt>W</tt> weekday</li>
5221<li><tt>_</tt>, <tt>'</tt>, <tt>/</tt>, <tt>.</tt>, <tt>,</tt>, <tt>T</tt> seperators for both time and date</li>
5222</ul>
5223</li>
5224<li>Return Value:
5225<ul>
5226
5227<li>a <tt>date/time/date_time</tt> value corresponding to <tt>date</tt>,</li>
5228<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
5229<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
5230<li>a type error will be raised if:</li>
5231<li>the first argument is any other non-date value,</li>
5232<li>the second argument is any other non-string value.</li>
5233</ul>
5234</li>
5235<li>
5236
5237<p>Example:</p>
5238
5239<div>
5240<div>
5241<pre class="source">parse_time(&quot;30:30&quot;,&quot;m:s&quot;);
5242</pre></div></div>
5243</li>
5244<li>
5245
5246<p>The expected result is:</p>
5247
5248<div>
5249<div>
5250<pre class="source">time(&quot;00:30:30.000Z&quot;)
5251</pre></div></div>
5252</li>
5253</ul></div>
5254<div class="section">
5255<h3><a name="print_date.2Fprint_time.2Fprint_datetime"></a>print_date/print_time/print_datetime</h3>
5256<ul>
5257
5258<li>
5259
5260<p>Syntax:</p>
5261
5262<div>
5263<div>
5264<pre class="source">print_date/print_time/print_datetime(date,formatting_expression)
5265</pre></div></div>
5266</li>
5267<li>
5268
5269<p>Creates a <tt>string</tt> representing a <tt>date/time/date_time</tt> value of the <tt>date</tt> using the formatting <tt>formatting_expression</tt></p>
5270</li>
5271<li>Arguments:
5272<ul>
5273
5274<li><tt>date</tt>: a <tt>date/time/datetime</tt> value.</li>
5275<li><tt>formatting_expression</tt> a <tt>string</tt> value providing the formatting for <tt>date_expression</tt>. Characters used to create date expression:</li>
5276<li><tt>h</tt> hours</li>
5277<li><tt>m</tt> minutes</li>
5278<li><tt>s</tt> seconds</li>
5279<li><tt>n</tt> milliseconds</li>
5280<li><tt>a</tt> am/pm</li>
5281<li><tt>z</tt> timezone</li>
5282<li><tt>Y</tt> year</li>
5283<li><tt>M</tt> month</li>
5284<li><tt>D</tt> day</li>
5285<li><tt>W</tt> weekday</li>
5286<li><tt>_</tt>, <tt>'</tt>, <tt>/</tt>, <tt>.</tt>, <tt>,</tt>, <tt>T</tt> seperators for both time and date</li>
5287</ul>
5288</li>
5289<li>Return Value:
5290<ul>
5291
5292<li>a <tt>string</tt> value corresponding to <tt>date</tt>,</li>
5293<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
5294<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
5295<li>a type error will be raised if:
5296<ul>
5297
5298<li>the first argument is any other non-date value,</li>
5299<li>the second argument is any other non-string value.</li>
5300</ul>
5301</li>
5302</ul>
5303</li>
5304<li>
5305
5306<p>Example:</p>
5307
5308<div>
5309<div>
5310<pre class="source">print_time(time(&quot;00:30:30.000Z&quot;),&quot;m:s&quot;);
5311</pre></div></div>
5312</li>
5313<li>
5314
5315<p>The expected result is:</p>
5316
5317<div>
5318<div>
5319<pre class="source">&quot;30:30&quot;
5320</pre></div></div>
5321</li>
5322</ul></div>
5323<div class="section">
5324<h3><a name="get_interval_start.2C_get_interval_end"></a>get_interval_start, get_interval_end</h3>
5325<ul>
5326
5327<li>
5328
5329<p>Syntax:</p>
5330
5331<div>
5332<div>
5333<pre class="source">get_interval_start/get_interval_end(interval)
5334</pre></div></div>
5335</li>
5336<li>
5337
5338<p>Gets the start/end of the given interval.</p>
5339</li>
5340<li>Arguments:
5341<ul>
5342
5343<li><tt>interval</tt>: the interval to be accessed.</li>
5344</ul>
5345</li>
5346<li>Return Value:
5347<ul>
5348
5349<li>a <tt>time</tt>, <tt>date</tt>, or <tt>datetime</tt> (depending on the time instances of the interval) representing the starting or ending time,</li>
5350<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5351<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5352<li>any other non-interval value will cause a type error.</li>
5353</ul>
5354</li>
5355<li>
5356
5357<p>Example:</p>
5358
5359<div>
5360<div>
5361<pre class="source">{
5362 &quot;start&quot;: get_interval_start(interval_start_from_date(&quot;1984-01-01&quot;, &quot;P1Y&quot;)),
5363 &quot;end&quot;: get_interval_end(interval_start_from_date(&quot;1984-01-01&quot;, &quot;P1Y&quot;))
5364};
5365</pre></div></div>
5366</li>
5367<li>
5368
5369<p>The expected result is:</p>
5370
5371<div>
5372<div>
5373<pre class="source">{ &quot;start&quot;: date(&quot;1984_01_01&quot;), &quot;end&quot;: date(&quot;1985_01_01&quot;) }
5374</pre></div></div>
5375</li>
5376</ul></div>
5377<div class="section">
5378<h3><a name="get_interval_start_date.2Fget_interval_start_datetimeget_interval_start_time.2C_get_interval_end_date.2Fget_interval_end_datetime.2Fget_interval_end_time"></a>get_interval_start_date/get_interval_start_datetimeget_interval_start_time, get_interval_end_date/get_interval_end_datetime/get_interval_end_time</h3>
5379<ul>
5380
5381<li>
5382
5383<p>Syntax:</p>
5384
5385<div>
5386<div>
5387<pre class="source">get_interval_start_date/get_interval_start_datetime/get_interval_start_time/get_interval_end_date/get_interval_end_datetime/get_interval_end_time(interval)
5388</pre></div></div>
5389</li>
5390<li>
5391
5392<p>Gets the start/end of the given interval for the specific date/datetime/time type.</p>
5393</li>
5394<li>Arguments:
5395<ul>
5396
5397<li><tt>interval</tt>: the interval to be accessed.</li>
5398</ul>
5399</li>
5400<li>Return Value:
5401<ul>
5402
5403<li>a <tt>time</tt>, <tt>date</tt>, or <tt>datetime</tt> (depending on the function) representing the starting or ending time,</li>
5404<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5405<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5406<li>any other non-interval value will cause a type error.</li>
5407</ul>
5408</li>
5409<li>
5410
5411<p>Example:</p>
5412
5413<div>
5414<div>
5415<pre class="source">{
5416 &quot;start1&quot;: get_interval_start_date(interval_start_from_date(&quot;1984-01-01&quot;, &quot;P1Y&quot;)),
5417 &quot;end1&quot;: get_interval_end_date(interval_start_from_date(&quot;1984-01-01&quot;, &quot;P1Y&quot;)),
5418 &quot;start2&quot;: get_interval_start_datetime(interval_start_from_datetime(&quot;1984-01-01T08:30:00.000&quot;, &quot;P1Y1H&quot;)),
5419 &quot;end2&quot;: get_interval_end_datetime(interval_start_from_datetime(&quot;1984-01-01T08:30:00.000&quot;, &quot;P1Y1H&quot;)),
5420 &quot;start3&quot;: get_interval_start_time(interval_start_from_time(&quot;08:30:00.000&quot;, &quot;P1H&quot;)),
5421 &quot;end3&quot;: get_interval_end_time(interval_start_from_time(&quot;08:30:00.000&quot;, &quot;P1H&quot;))
5422};
5423</pre></div></div>
5424</li>
5425<li>
5426
5427<p>The expected result is:</p>
5428
5429<div>
5430<div>
5431<pre class="source">{
5432 &quot;start1&quot;: date(&quot;1984-01-01&quot;),
5433 &quot;end1&quot;: date(&quot;1985-01-01&quot;),
5434 &quot;start2&quot;: datetime(&quot;1984-01-01T08:30:00.000Z&quot;),
5435 &quot;end2&quot;: datetime(&quot;1985-01-01T09:30:00.000Z&quot;),
5436 &quot;start3&quot;: time(&quot;08:30:00.000Z&quot;),
5437 &quot;end3&quot;: time(&quot;09:30:00.000Z&quot;)
5438}
5439</pre></div></div>
5440</li>
5441</ul></div>
5442<div class="section">
5443<h3><a name="get_overlapping_interval"></a>get_overlapping_interval</h3>
5444<ul>
5445
5446<li>
5447
5448<p>Syntax:</p>
5449
5450<div>
5451<div>
5452<pre class="source">get_overlapping_interval(interval1, interval2)
5453</pre></div></div>
5454</li>
5455<li>
5456
5457<p>Gets the start/end of the given interval for the specific date/datetime/time type.</p>
5458</li>
5459<li>Arguments:
5460<ul>
5461
5462<li><tt>interval1</tt>: an <tt>interval</tt> value</li>
5463<li><tt>interval2</tt>: an <tt>interval</tt> value</li>
5464</ul>
5465</li>
5466<li>Return Value:
5467<ul>
5468
5469<li>an <tt>interval</tt> that is overlapping <tt>interval1</tt> and <tt>interval2</tt>. If <tt>interval1</tt> and <tt>interval2</tt> do not overlap <tt>null</tt> is returned. Note each interval must be of the same type.</li>
5470<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
5471<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
5472<li>any other non-interval input value will cause a type error.</li>
5473</ul>
5474</li>
5475<li>
5476
5477<p>Example:</p>
5478
5479<div>
5480<div>
5481<pre class="source">{ &quot;overlap1&quot;: get_overlapping_interval(interval(time(&quot;11:23:39&quot;), time(&quot;18:27:19&quot;)), interval(time(&quot;12:23:39&quot;), time(&quot;23:18:00&quot;))),
5482 &quot;overlap2&quot;: get_overlapping_interval(interval(time(&quot;12:23:39&quot;), time(&quot;18:27:19&quot;)), interval(time(&quot;07:19:39&quot;), time(&quot;09:18:00&quot;))),
5483 &quot;overlap3&quot;: get_overlapping_interval(interval(date(&quot;1980-11-30&quot;), date(&quot;1999-09-09&quot;)), interval(date(&quot;2013-01-01&quot;), date(&quot;2014-01-01&quot;))),
5484 &quot;overlap4&quot;: get_overlapping_interval(interval(date(&quot;1980-11-30&quot;), date(&quot;2099-09-09&quot;)), interval(date(&quot;2013-01-01&quot;), date(&quot;2014-01-01&quot;))),
5485 &quot;overlap5&quot;: get_overlapping_interval(interval(datetime(&quot;1844-03-03T11:19:39&quot;), datetime(&quot;2000-10-30T18:27:19&quot;)), interval(datetime(&quot;1989-03-04T12:23:39&quot;), datetime(&quot;2009-10-10T23:18:00&quot;))),
5486 &quot;overlap6&quot;: get_overlapping_interval(interval(datetime(&quot;1989-03-04T12:23:39&quot;), datetime(&quot;2000-10-30T18:27:19&quot;)), interval(datetime(&quot;1844-03-03T11:19:39&quot;), datetime(&quot;1888-10-10T23:18:00&quot;)))
5487};
5488</pre></div></div>
5489</li>
5490<li>
5491
5492<p>The expected result is:</p>
5493
5494<div>
5495<div>
5496<pre class="source">{ &quot;overlap1&quot;: interval(time(&quot;12:23:39.000Z&quot;), time(&quot;18:27:19.000Z&quot;)),
5497 &quot;overlap2&quot;: null,
5498 &quot;overlap3&quot;: null,
5499 &quot;overlap4&quot;: interval(date(&quot;2013-01-01&quot;), date(&quot;2014_01_01&quot;)),
5500 &quot;overlap5&quot;: interval(datetime(&quot;1989-03-04T12:23:39.000Z&quot;), datetime(&quot;2000-10-30T18:27:19.000Z&quot;)),
5501 &quot;overlap6&quot;: null
5502}
5503</pre></div></div>
5504</li>
5505</ul></div>
5506<div class="section">
5507<h3><a name="interval_bin"></a>interval_bin</h3>
5508<ul>
5509
5510<li>
5511
5512<p>Syntax:</p>
5513
5514<div>
5515<div>
5516<pre class="source">interval_bin(time_to_bin, time_bin_anchor, duration_bin_size)
5517</pre></div></div>
5518</li>
5519<li>
5520
5521<p>Returns the <tt>interval</tt> value representing the bin containing the <tt>time_to_bin</tt> value.</p>
5522</li>
5523<li>Arguments:
5524<ul>
5525
5526<li><tt>time_to_bin</tt>: a date/time/datetime value representing the time to be binned.</li>
5527<li><tt>time_bin_anchor</tt>: a date/time/datetime value representing an anchor of a bin starts. The type of this argument should be the same as the first <tt>time_to_bin</tt> argument.</li>
5528<li><tt>duration_bin_size</tt>: the duration value representing the size of the bin, in the type of year_month_duration or day_time_duration. The type of this duration should be compatible with the type of <tt>time_to_bin</tt>, so that the arithmetic operation between <tt>time_to_bin</tt> and <tt>duration_bin_size</tt> is well_defined. Currently AsterixDB supports the following arithmetic operations:
5529<ul>
5530
5531<li>datetime +|_ year_month_duration</li>
5532<li>datetime +|_ day_time_duration</li>
5533<li>date +|_ year_month_duration</li>
5534<li>date +|_ day_time_duration</li>
5535<li>time +|_ day_time_duration</li>
5536</ul>
5537</li>
5538</ul>
5539</li>
5540<li>Return Value:
5541<ul>
5542
5543<li>a <tt>interval</tt> value representing the bin containing the <tt>time_to_bin</tt> value. Note that the internal type of this interval value should be the same as the <tt>time_to_bin</tt> type,</li>
5544<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
5545<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
5546<li>a type error will be raised if:
5547<ul>
5548
5549<li>the first argument or the second argument is any other non-date/non-time/non-datetime value,</li>
5550<li>or, the second argument is any other non-year_month_duration/non-day_time_duration value.</li>
5551</ul>
5552</li>
5553</ul>
5554</li>
5555<li>
5556
5557<p>Example:</p>
5558
5559<div>
5560<div>
5561<pre class="source">{
5562 &quot;bin1&quot;: interval_bin(date(&quot;2010-10-30&quot;), date(&quot;1990-01-01&quot;), year_month_duration(&quot;P1Y&quot;)),
5563 &quot;bin2&quot;: interval_bin(datetime(&quot;1987-11-19T23:49:23.938&quot;), datetime(&quot;1990-01-01T00:00:00.000Z&quot;), year_month_duration(&quot;P6M&quot;)),
5564 &quot;bin3&quot;: interval_bin(time(&quot;12:23:34.930+07:00&quot;), time(&quot;00:00:00&quot;), day_time_duration(&quot;PT1M&quot;)),
5565 &quot;bin4&quot;: interval_bin(datetime(&quot;1987-11-19T23:49:23.938&quot;), datetime(&quot;2013-01-01T00:00:00.000&quot;), day_time_duration(&quot;PT24H&quot;))
5566};
5567</pre></div></div>
5568</li>
5569<li>
5570
5571<p>The expected result is:</p>
5572
5573<div>
5574<div>
5575<pre class="source">{
5576 &quot;bin1&quot;: interval(date(&quot;2010-01-01&quot;),date(&quot;2011-01-01&quot;)),
5577 &quot;bin2&quot;: interval(datetime(&quot;1987-07-01T00:00:00.000Z&quot;), datetime(&quot;1988-01-01T00:00:00.000Z&quot;)),
5578 &quot;bin3&quot;: interval(time(&quot;05:23:00.000Z&quot;), time(&quot;05:24:00.000Z&quot;)),
5579 &quot;bin4&quot;: interval(datetime(&quot;1987-11-19T00:00:00.000Z&quot;), datetime(&quot;1987-11-20T00:00:00.000Z&quot;))
5580}
5581</pre></div></div>
5582</li>
5583</ul></div>
5584<div class="section">
5585<h3><a name="interval_start_from_date.2Ftime.2Fdatetime"></a>interval_start_from_date/time/datetime</h3>
5586<ul>
5587
5588<li>
5589
5590<p>Syntax:</p>
5591
5592<div>
5593<div>
5594<pre class="source">interval_start_from_date/time/datetime(date/time/datetime, duration)
5595</pre></div></div>
5596</li>
5597<li>
5598
5599<p>Construct an <tt>interval</tt> value by the given starting <tt>date</tt>/<tt>time</tt>/<tt>datetime</tt> and the <tt>duration</tt> that the interval lasts.</p>
5600</li>
5601<li>Arguments:
5602<ul>
5603
5604<li><tt>date/time/datetime</tt>: a <tt>string</tt> representing a <tt>date</tt>, <tt>time</tt> or <tt>datetime</tt>, or a <tt>date</tt>/<tt>time</tt>/<tt>datetime</tt> value, representing the starting time point.</li>
5605<li><tt>duration</tt>: a <tt>string</tt> or <tt>duration</tt> value representing the duration of the interval. Note that duration cannot be negative value.</li>
5606</ul>
5607</li>
5608<li>Return Value:
5609<ul>
5610
5611<li>an <tt>interval</tt> value representing the interval starting from the given time point with the length of duration,</li>
5612<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
5613<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
5614<li>a type error will be raised if:
5615<ul>
5616
5617<li>the first argument or the second argument is any other non-date/non-time/non-datetime value,</li>
5618<li>or, the second argument is any other non-duration value.</li>
5619</ul>
5620</li>
5621</ul>
5622</li>
5623<li>
5624
5625<p>Example:</p>
5626
5627<div>
5628<div>
5629<pre class="source">{
5630 &quot;interval1&quot;: interval_start_from_date(&quot;1984-01-01&quot;, &quot;P1Y&quot;),
5631 &quot;interval2&quot;: interval_start_from_time(time(&quot;02:23:28.394&quot;), &quot;PT3H24M&quot;),
5632 &quot;interval3&quot;: interval_start_from_datetime(&quot;1999-09-09T09:09:09.999&quot;, duration(&quot;P2M30D&quot;))
5633};
5634</pre></div></div>
5635</li>
5636<li>
5637
5638<p>The expectecd result is:</p>
5639
5640<div>
5641<div>
5642<pre class="source">{
5643 &quot;interval1&quot;: interval(date(&quot;1984-01-01&quot;), date(&quot;1985-01-01&quot;)),
5644 &quot;interval2&quot;: interval(time(&quot;02:23:28.394Z&quot;), time(&quot;05:47:28.394Z&quot;)),
5645 &quot;interval3&quot;: interval(datetime(&quot;1999-09-09T09:09:09.999Z&quot;), datetime(&quot;1999-12-09T09:09:09.999Z&quot;))
5646}
5647</pre></div></div>
5648</li>
5649</ul></div>
5650<div class="section">
5651<h3><a name="overlap_bins"></a>overlap_bins</h3>
5652<ul>
5653
5654<li>
5655
5656<p>Return Value:</p>
5657<ul>
5658
5659<li>a <tt>interval</tt> value representing the bin containing the <tt>time_to_bin</tt> value. Note that the internal type of this interval value should be the same as the <tt>time_to_bin</tt> type.</li>
5660</ul>
5661</li>
5662<li>
5663
5664<p>Syntax:</p>
5665
5666<div>
5667<div>
5668<pre class="source">overlap_bins(interval, time_bin_anchor, duration_bin_size)
5669</pre></div></div>
5670</li>
5671<li>
5672
5673<p>Returns an ordered list of <tt>interval</tt> values representing each bin that is overlapping the <tt>interval</tt>.</p>
5674</li>
5675<li>Arguments:
5676<ul>
5677
5678<li><tt>interval</tt>: an <tt>interval</tt> value</li>
5679<li><tt>time_bin_anchor</tt>: a date/time/datetime value representing an anchor of a bin starts. The type of this argument should be the same as the first <tt>time_to_bin</tt> argument.</li>
5680<li><tt>duration_bin_size</tt>: the duration value representing the size of the bin, in the type of year_month_duration or day_time_duration. The type of this duration should be compatible with the type of <tt>time_to_bin</tt>, so that the arithmetic operation between <tt>time_to_bin</tt> and <tt>duration_bin_size</tt> is well_defined. Currently AsterixDB supports the following arithmetic operations:
5681<ul>
5682
5683<li>datetime +|_ year_month_duration</li>
5684<li>datetime +|_ day_time_duration</li>
5685<li>date +|_ year_month_duration</li>
5686<li>date +|_ day_time_duration</li>
5687<li>time +|_ day_time_duration</li>
5688</ul>
5689</li>
5690</ul>
5691</li>
5692<li>Return Value:
5693<ul>
5694
5695<li>a ordered list of <tt>interval</tt> values representing each bin that is overlapping the <tt>interval</tt>. Note that the internal type as <tt>time_to_bin</tt> and <tt>duration_bin_size</tt>.</li>
5696<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
5697<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
5698<li>a type error will be raised if:
5699<ul>
5700
5701<li>the first arugment is any other non-interval value,</li>
5702<li>or, the second argument is any other non-date/non-time/non-datetime value,</li>
5703<li>or, the second argument is any other non-year_month_duration/non-day_time_duration value.</li>
5704</ul>
5705</li>
5706</ul>
5707</li>
5708<li>
5709
5710<p>Example:</p>
5711
5712<div>
5713<div>
5714<pre class="source">{
5715 &quot;timebins&quot;: overlap_bins(interval(time(&quot;17:23:37&quot;), time(&quot;18:30:21&quot;)), time(&quot;00:00:00&quot;), day_time_duration(&quot;PT30M&quot;)),
5716 &quot;datebins&quot;: overlap_bins(interval(date(&quot;1984-03-17&quot;), date(&quot;2013-08-22&quot;)), date(&quot;1990-01-01&quot;), year_month_duration(&quot;P10Y&quot;)),
5717 &quot;datetimebins&quot;: overlap_bins(interval(datetime(&quot;1800-01-01T23:59:48.938&quot;), datetime(&quot;2015-07-26T13:28:30.218&quot;)),
5718 datetime(&quot;1900-01-01T00:00:00.000&quot;), year_month_duration(&quot;P100Y&quot;))
5719};
5720</pre></div></div>
5721</li>
5722<li>
5723
5724<p>The expected result is:</p>
5725
5726<div>
5727<div>
5728<pre class="source">{
5729 &quot;timebins&quot;: [
5730 interval(time(&quot;17:00:00.000Z&quot;), time(&quot;17:30:00.000Z&quot;)),
5731 interval(time(&quot;17:30:00.000Z&quot;), time(&quot;18:00:00.000Z&quot;)),
5732 interval(time(&quot;18:00:00.000Z&quot;), time(&quot;18:30:00.000Z&quot;)),
5733 interval(time(&quot;18:30:00.000Z&quot;), time(&quot;19:00:00.000Z&quot;))
5734 ],
5735 &quot;datebins&quot;: [
5736 interval(date(&quot;1980-01-01&quot;), date(&quot;1990-01-01&quot;)),
5737 interval(date(&quot;1990-01-01&quot;), date(&quot;2000-01-01&quot;)),
5738 interval(date(&quot;2000-01-01&quot;), date(&quot;2010-01-01&quot;)),
5739 interval(date(&quot;2010-01-01&quot;), date(&quot;2020-01-01&quot;))
5740 ],
5741 &quot;datetimebins&quot;: [
5742 interval(datetime(&quot;1800-01-01T00:00:00.000Z&quot;), datetime(&quot;1900-01-01T00:00:00.000Z&quot;)),
5743 interval(datetime(&quot;1900-01-01T00:00:00.000Z&quot;), datetime(&quot;2000-01-01T00:00:00.000Z&quot;)),
5744 interval(datetime(&quot;2000-01-01T00:00:00.000Z&quot;), datetime(&quot;2100-01-01T00:00:00.000Z&quot;))
5745 ]
5746};
5747</pre></div></div>
5748</li>
5749</ul><!--
5750 ! Licensed to the Apache Software Foundation (ASF) under one
5751 ! or more contributor license agreements. See the NOTICE file
5752 ! distributed with this work for additional information
5753 ! regarding copyright ownership. The ASF licenses this file
5754 ! to you under the Apache License, Version 2.0 (the
5755 ! "License"); you may not use this file except in compliance
5756 ! with the License. You may obtain a copy of the License at
5757 !
5758 ! http://www.apache.org/licenses/LICENSE-2.0
5759 !
5760 ! Unless required by applicable law or agreed to in writing,
5761 ! software distributed under the License is distributed on an
5762 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
5763 ! KIND, either express or implied. See the License for the
5764 ! specific language governing permissions and limitations
5765 ! under the License.
5766 !-->
5767</div>
5768<div class="section">
5769<h3><a name="interval_before.2C_interval_after"></a>interval_before, interval_after</h3>
5770<ul>
5771
5772<li>
5773
5774<p>Syntax:</p>
5775
5776<div>
5777<div>
5778<pre class="source">interval_before(interval1, interval2)
5779interval_after(interval1, interval2)
5780</pre></div></div>
5781</li>
5782<li>
5783
5784<p>These two functions check whether an interval happens before/after another interval.</p>
5785</li>
5786<li>Arguments:
5787<ul>
5788
5789<li><tt>interval1</tt>, <tt>interval2</tt>: two intervals to be compared</li>
5790</ul>
5791</li>
5792<li>Return Value:
5793<ul>
5794
5795<li>a <tt>boolean</tt> value. Specifically, <tt>interval_before(interval1, interval2)</tt> is true if and only if <tt>interval1.end &lt; interval2.start</tt>, and <tt>interval_after(interval1, interval2)</tt> is true if and only if <tt>interval1.start &gt; interval2.end</tt>.</li>
5796<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5797<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
5798<li>any other non-interval input value will cause a type error.</li>
5799</ul>
5800</li>
5801<li>
5802
5803<p>Examples:</p>
5804
5805<div>
5806<div>
5807<pre class="source">{
5808 &quot;interval_before&quot;: interval_before(interval(date(&quot;2000-01-01&quot;), date(&quot;2005-01-01&quot;)),
5809 interval(date(&quot;2005-05-01&quot;), date(&quot;2012-09-09&quot;))),
5810 &quot;interval_after&quot;: interval_after(interval(date(&quot;2005-05-01&quot;), date(&quot;2012-09-09&quot;)),
5811 interval(date(&quot;2000-01-01&quot;), date(&quot;2005-01-01&quot;)))
5812};
5813</pre></div></div>
5814</li>
5815<li>
5816
5817<p>The expected result is:</p>
5818
5819<div>
5820<div>
5821<pre class="source">{ &quot;interval_before&quot;: true, &quot;interval_after&quot;: true }
5822</pre></div></div>
5823</li>
5824</ul></div>
5825<div class="section">
5826<h3><a name="interval_covers.2C_interval_covered_by"></a>interval_covers, interval_covered_by</h3>
5827<ul>
5828
5829<li>
5830
5831<p>Syntax:</p>
5832
5833<div>
5834<div>
5835<pre class="source">interval_covers(interval1, interval2)
5836interval_covered_by(interval1, interval2)
5837</pre></div></div>
5838</li>
5839<li>
5840
5841<p>These two functions check whether one interval covers the other interval.</p>
5842</li>
5843<li>Arguments:
5844<ul>
5845
5846<li><tt>interval1</tt>, <tt>interval2</tt>: two intervals to be compared</li>
5847</ul>
5848</li>
5849<li>Return Value:
5850<ul>
5851
5852<li>
5853
5854<p>a <tt>boolean</tt> value. Specifically, <tt>interval_covers(interval1, interval2)</tt> is true if and only if</p>
5855<p>interval1.start &lt;= interval2.start AND interval1.end &gt;= interval2.end</p>
5856<p><tt>interval_covered_by(interval1, interval2)</tt> is true if and only if</p>
5857<p>interval2.start &lt;= interval1.start AND interval2.end &gt;= interval1.end</p>
5858</li>
5859<li>
5860
5861<p><tt>missing</tt> if the argument is a <tt>missing</tt> value,</p>
5862</li>
5863<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
5864<li>any other non-interval input value will cause a type error.</li>
5865</ul>
5866</li>
5867<li>
5868
5869<p>Examples:</p>
5870
5871<div>
5872<div>
5873<pre class="source">{
5874 &quot;interval_covers&quot;: interval_covers(interval(date(&quot;2000-01-01&quot;), date(&quot;2005-01-01&quot;)),
5875 interval(date(&quot;2000-03-01&quot;), date(&quot;2004-09-09&quot;))),
5876 &quot;interval_covered_by&quot;: interval_covered_by(interval(date(&quot;2006-08-01&quot;), date(&quot;2007-03-01&quot;)),
5877 interval(date(&quot;2004-09-10&quot;), date(&quot;2012-08-01&quot;)))
5878};
5879</pre></div></div>
5880</li>
5881<li>
5882
5883<p>The expected result is:</p>
5884
5885<div>
5886<div>
5887<pre class="source">{ &quot;interval_covers&quot;: true, &quot;interval_covered_by&quot;: true }
5888</pre></div></div>
5889</li>
5890</ul></div>
5891<div class="section">
5892<h3><a name="interval_overlaps.2C_interval_overlapped_by"></a>interval_overlaps, interval_overlapped_by</h3>
5893<ul>
5894
5895<li>
5896
5897<p>Syntax:</p>
5898
5899<div>
5900<div>
5901<pre class="source">interval_overlaps(interval1, interval2)
5902interval_overlapped_by(interval1, interval2)
5903</pre></div></div>
5904</li>
5905<li>
5906
5907<p>These functions check whether two intervals overlap with each other.</p>
5908</li>
5909<li>Arguments:
5910<ul>
5911
5912<li><tt>interval1</tt>, <tt>interval2</tt>: two intervals to be compared</li>
5913</ul>
5914</li>
5915<li>Return Value:
5916<ul>
5917
5918<li>a <tt>boolean</tt> value. Specifically, <tt>interval_overlaps(interval1, interval2)</tt> is true if and only if
5919<p>interval1.start &lt; interval2.start AND interval2.end &gt; interval1.end AND interval1.end &gt; interval2.start</p></li>
5920</ul>
5921<p><tt>interval_overlapped_by(interval1, interval2)</tt> is true if and only if</p>
5922
5923<div>
5924<div>
5925<pre class="source">interval2.start &lt; interval1.start
5926AND interval1.end &gt; interval2.end
5927AND interval2.end &gt; interval1.start
5928</pre></div></div>
5929
5930<ul>
5931
5932<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5933<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
5934<li>any other non-interval input value will cause a type error.</li>
5935</ul>
5936<p>Note that <tt>interval_overlaps</tt> and <tt>interval_overlapped_by</tt> are following the Allen&#x2019;s relations on the definition of overlap.</p>
5937</li>
5938<li>
5939
5940<p>Examples:</p>
5941
5942<div>
5943<div>
5944<pre class="source">{
5945 &quot;overlaps&quot;: interval_overlaps(interval(date(&quot;2000-01-01&quot;), date(&quot;2005-01-01&quot;)),
5946 interval(date(&quot;2004-05-01&quot;), date(&quot;2012-09-09&quot;))),
5947 &quot;overlapped_by&quot;: interval_overlapped_by(interval(date(&quot;2006-08-01&quot;), date(&quot;2007-03-01&quot;)),
5948 interval(date(&quot;2004-05-01&quot;), date(&quot;2012-09-09&quot;))))
5949};
5950</pre></div></div>
5951</li>
5952<li>
5953
5954<p>The expected result is:</p>
5955
5956<div>
5957<div>
5958<pre class="source">{ &quot;overlaps&quot;: true, &quot;overlapped_by&quot;: true }
5959</pre></div></div>
5960</li>
5961</ul></div>
5962<div class="section">
5963<h3><a name="interval_overlapping"></a>interval_overlapping</h3>
5964<p>Note that <tt>interval_overlapping</tt> is not an Allen&#x2019;s Relation, but syntactic sugar we added for the case that the intersect of two intervals is not empty. Basically this function returns true if any of these functions return true: <tt>interval_overlaps</tt>, <tt>interval_overlapped_by</tt>, <tt>interval_covers</tt>, or <tt>interval_covered_by</tt>.</p>
5965<ul>
5966
5967<li>
5968
5969<p>Syntax:</p>
5970
5971<div>
5972<div>
5973<pre class="source">interval_overlapping(interval1, interval2)
5974</pre></div></div>
5975</li>
5976<li>
5977
5978<p>This functions check whether two intervals share any points with each other.</p>
5979</li>
5980<li>Arguments:
5981<ul>
5982
5983<li><tt>interval1</tt>, <tt>interval2</tt>: two intervals to be compared</li>
5984</ul>
5985</li>
5986<li>Return Value:
5987<ul>
5988
5989<li>
5990
5991<p>a <tt>boolean</tt> value. Specifically, <tt>interval_overlapping(interval1, interval2)</tt> is true if</p>
5992<p>interval1.start &lt; interval2.end AND interval1.end &gt; interval2.start</p>
5993</li>
5994<li>
5995
5996<p><tt>missing</tt> if the argument is a <tt>missing</tt> value,</p>
5997</li>
5998<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
5999<li>any other non-interval input value will cause a type error.</li>
6000</ul>
6001</li>
6002<li>
6003
6004<p>Examples:</p>
6005
6006<div>
6007<div>
6008<pre class="source">{
6009 &quot;overlapping1&quot;: interval_overlapping(interval(date(&quot;2000-01-01&quot;), date(&quot;2005-01-01&quot;)),
6010 interval(date(&quot;2004-05-01&quot;), date(&quot;2012-09-09&quot;))),
6011 &quot;overlapping2&quot;: interval_overlapping(interval(date(&quot;2006-08-01&quot;), date(&quot;2007-03-01&quot;)),
6012 interval(date(&quot;2004-09-10&quot;), date(&quot;2006-12-31&quot;)))
6013};
6014</pre></div></div>
6015</li>
6016<li>
6017
6018<p>The expected result is:</p>
6019
6020<div>
6021<div>
6022<pre class="source">{ &quot;overlapping1&quot;: true, &quot;overlapping2&quot;: true }
6023</pre></div></div>
6024</li>
6025</ul></div>
6026<div class="section">
6027<h3><a name="interval_meets.2C_interval_met_by"></a>interval_meets, interval_met_by</h3>
6028<ul>
6029
6030<li>
6031
6032<p>Syntax:</p>
6033
6034<div>
6035<div>
6036<pre class="source">interval_meets(interval1, interval2)
6037interval_met_by(interval1, interval2)
6038</pre></div></div>
6039</li>
6040<li>
6041
6042<p>These two functions check whether an interval meets with another interval.</p>
6043</li>
6044<li>Arguments:
6045<ul>
6046
6047<li><tt>interval1</tt>, <tt>interval2</tt>: two intervals to be compared</li>
6048</ul>
6049</li>
6050<li>Return Value:
6051<ul>
6052
6053<li>a <tt>boolean</tt> value. Specifically, <tt>interval_meets(interval1, interval2)</tt> is true if and only if <tt>interval1.end = interval2.start</tt>, and <tt>interval_met_by(interval1, interval2)</tt> is true if and only if <tt>interval1.start = interval2.end</tt>. If any of the two inputs is <tt>null</tt>, <tt>null</tt> is returned.</li>
6054<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
6055<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6056<li>any other non-interval input value will cause a type error.</li>
6057</ul>
6058</li>
6059<li>
6060
6061<p>Examples:</p>
6062
6063<div>
6064<div>
6065<pre class="source">{
6066 &quot;meets&quot;: interval_meets(interval(date(&quot;2000-01-01&quot;), date(&quot;2005-01-01&quot;)),
6067 interval(date(&quot;2005-01-01&quot;), date(&quot;2012-09-09&quot;))),
6068 &quot;metby&quot;: interval_met_by(interval(date(&quot;2006-08-01&quot;), date(&quot;2007-03-01&quot;)),
6069 interval(date(&quot;2004-09-10&quot;), date(&quot;2006-08-01&quot;)))
6070};
6071</pre></div></div>
6072</li>
6073<li>
6074
6075<p>The expected result is:</p>
6076
6077<div>
6078<div>
6079<pre class="source">{ &quot;meets&quot;: true, &quot;metby&quot;: true }
6080</pre></div></div>
6081</li>
6082</ul></div>
6083<div class="section">
6084<h3><a name="interval_starts.2C_interval_started_by"></a>interval_starts, interval_started_by</h3>
6085<ul>
6086
6087<li>
6088
6089<p>Syntax:</p>
6090
6091<div>
6092<div>
6093<pre class="source">interval_starts(interval1, interval2)
6094interval_started_by(interval1, interval2)
6095</pre></div></div>
6096</li>
6097<li>
6098
6099<p>These two functions check whether one interval starts with the other interval.</p>
6100</li>
6101<li>Arguments:
6102<ul>
6103
6104<li><tt>interval1</tt>, <tt>interval2</tt>: two intervals to be compared</li>
6105</ul>
6106</li>
6107<li>Return Value:
6108<ul>
6109
6110<li>a <tt>boolean</tt> value. Specifically, <tt>interval_starts(interval1, interval2)</tt> returns true if and only if
6111<p>interval1.start = interval2.start AND interval1.end &lt;= interval2.end</p></li>
6112</ul>
6113<p><tt>interval_started_by(interval1, interval2)</tt> returns true if and only if</p>
6114
6115<div>
6116<div>
6117<pre class="source">interval1.start = interval2.start
6118AND interval2.end &lt;= interval1.end
6119</pre></div></div>
6120
6121<ul>
6122
6123<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
6124<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6125<li>any other non-interval input value will cause a type error.</li>
6126</ul>
6127</li>
6128<li>
6129
6130<p>Examples:</p>
6131
6132<div>
6133<div>
6134<pre class="source">{
6135 &quot;interval_starts&quot;: interval_starts(interval(date(&quot;2000-01-01&quot;), date(&quot;2005-01-01&quot;)),
6136 interval(date(&quot;2000-01-01&quot;), date(&quot;2012-09-09&quot;))),
6137 &quot;interval_started_by&quot;: interval_started_by(interval(date(&quot;2006-08-01&quot;), date(&quot;2007-03-01&quot;)),
6138 interval(date(&quot;2006-08-01&quot;), date(&quot;2006-08-02&quot;)))
6139};
6140</pre></div></div>
6141</li>
6142<li>
6143
6144<p>The expected result is:</p>
6145
6146<div>
6147<div>
6148<pre class="source">{ &quot;interval_starts&quot;: true, &quot;interval_started_by&quot;: true }
6149</pre></div></div>
6150</li>
6151</ul></div>
6152<div class="section">
6153<h3><a name="interval_ends.2C_interval_ended_by"></a>interval_ends, interval_ended_by</h3>
6154<ul>
6155
6156<li>
6157
6158<p>Syntax:</p>
6159
6160<div>
6161<div>
6162<pre class="source">interval_ends(interval1, interval2)
6163interval_ended_by(interval1, interval2)
6164</pre></div></div>
6165</li>
6166<li>
6167
6168<p>These two functions check whether one interval ends with the other interval.</p>
6169</li>
6170<li>Arguments:
6171<ul>
6172
6173<li><tt>interval1</tt>, <tt>interval2</tt>: two intervals to be compared</li>
6174</ul>
6175</li>
6176<li>Return Value:
6177<ul>
6178
6179<li>
6180
6181<p>a <tt>boolean</tt> value. Specifically, <tt>interval_ends(interval1, interval2)</tt> returns true if and only if</p>
6182<p>interval1.end = interval2.end AND interval1.start &gt;= interval2.start</p>
6183<p><tt>interval_ended_by(interval1, interval2)</tt> returns true if and only if</p>
6184<p>interval2.end = interval1.end AND interval2.start &gt;= interval1.start</p>
6185</li>
6186<li>
6187
6188<p><tt>missing</tt> if the argument is a <tt>missing</tt> value,</p>
6189</li>
6190<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6191<li>any other non-interval input value will cause a type error.</li>
6192</ul>
6193</li>
6194<li>
6195
6196<p>Examples:</p>
6197
6198<div>
6199<div>
6200<pre class="source">{
6201 &quot;interval_ends&quot;: interval_ends(interval(date(&quot;2000-01-01&quot;), date(&quot;2005-01-01&quot;)),
6202 interval(date(&quot;1998-01-01&quot;), date(&quot;2005-01-01&quot;))),
6203 &quot;interval_ended_by&quot;: interval_ended_by(interval(date(&quot;2006-08-01&quot;), date(&quot;2007-03-01&quot;)),
6204 interval(date(&quot;2006-09-10&quot;), date(&quot;2007-03-01&quot;)))
6205};
6206</pre></div></div>
6207</li>
6208<li>
6209
6210<p>The expected result is:</p>
6211
6212<div>
6213<div>
6214<pre class="source">{ &quot;interval_ends&quot;: true, &quot;interval_ended_by&quot;: true }
6215</pre></div></div>
6216</li>
6217</ul><!--
6218 ! Licensed to the Apache Software Foundation (ASF) under one
6219 ! or more contributor license agreements. See the NOTICE file
6220 ! distributed with this work for additional information
6221 ! regarding copyright ownership. The ASF licenses this file
6222 ! to you under the Apache License, Version 2.0 (the
6223 ! "License"); you may not use this file except in compliance
6224 ! with the License. You may obtain a copy of the License at
6225 !
6226 ! http://www.apache.org/licenses/LICENSE-2.0
6227 !
6228 ! Unless required by applicable law or agreed to in writing,
6229 ! software distributed under the License is distributed on an
6230 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
6231 ! KIND, either express or implied. See the License for the
6232 ! specific language governing permissions and limitations
6233 ! under the License.
6234 !-->
6235</div></div>
6236<div class="section">
6237<h2><a name="Object_Functions"></a><a name="ObjectFunctions" id="ObjectFunctions">Object Functions</a></h2>
6238<div class="section">
6239<h3><a name="get_object_fields"></a>get_object_fields</h3>
6240<ul>
6241
6242<li>
6243
6244<p>Syntax:</p>
6245
6246<div>
6247<div>
6248<pre class="source">get_object_fields(input_object)
6249</pre></div></div>
6250</li>
6251<li>
6252
6253<p>Access the object field names, type and open status for a given object.</p>
6254</li>
6255<li>Arguments:
6256<ul>
6257
6258<li><tt>input_object</tt> : a object value.</li>
6259</ul>
6260</li>
6261<li>Return Value:
6262<ul>
6263
6264<li>an array of <tt>object</tt> values that include the field_name <tt>string</tt>, field_type <tt>string</tt>, is_open <tt>boolean</tt> (used for debug purposes only: <tt>true</tt> if field is open and <tt>false</tt> otherwise), and optional nested <tt>orderedList</tt> for the values of a nested object,</li>
6265<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
6266<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
6267<li>any other non-object input value will cause a type error.</li>
6268</ul>
6269</li>
6270<li>
6271
6272<p>Example:</p>
6273
6274<div>
6275<div>
6276<pre class="source">get_object_fields(
6277 {
6278 &quot;id&quot;: 1,
6279 &quot;project&quot;: &quot;AsterixDB&quot;,
6280 &quot;address&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;},
6281 &quot;related&quot;: [&quot;Hivestrix&quot;, &quot;Preglix&quot;, &quot;Apache VXQuery&quot;]
6282 }
6283 );
6284</pre></div></div>
6285</li>
6286<li>
6287
6288<p>The expected result is:</p>
6289
6290<div>
6291<div>
6292<pre class="source">[
6293 { &quot;field-name&quot;: &quot;id&quot;, &quot;field-type&quot;: &quot;INT64&quot;, &quot;is-open&quot;: false },
6294 { &quot;field-name&quot;: &quot;project&quot;, &quot;field-type&quot;: &quot;STRING&quot;, &quot;is-open&quot;: false },
6295 { &quot;field-name&quot;: &quot;address&quot;, &quot;field-type&quot;: &quot;RECORD&quot;, &quot;is-open&quot;: false,
6296 &quot;nested&quot;: [
6297 { &quot;field-name&quot;: &quot;city&quot;, &quot;field-type&quot;: &quot;STRING&quot;, &quot;is-open&quot;: false },
6298 { &quot;field-name&quot;: &quot;state&quot;, &quot;field-type&quot;: &quot;STRING&quot;, &quot;is-open&quot;: false }
6299 ]
6300 },
6301 { &quot;field-name&quot;:
6302 &quot;related&quot;,
6303 &quot;field-type&quot;: &quot;ORDEREDLIST&quot;,
6304 &quot;is-open&quot;: false,
6305 &quot;list&quot;: [
6306 { &quot;field-type&quot;: &quot;STRING&quot; },
6307 { &quot;field-type&quot;: &quot;STRING&quot; },
6308 { &quot;field-type&quot;: &quot;STRING&quot; }
6309 ]
6310 }
6311]
6312</pre></div></div>
6313</li>
6314</ul>
6315<p>]</p></div>
6316<div class="section">
6317<h3><a name="get_object_field_value"></a>get_object_field_value</h3>
6318<ul>
6319
6320<li>
6321
6322<p>Syntax:</p>
6323
6324<div>
6325<div>
6326<pre class="source">get_object_field_value(input_object, string)
6327</pre></div></div>
6328</li>
6329<li>
6330
6331<p>Access the field name given in the <tt>string_expression</tt> from the <tt>object_expression</tt>.</p>
6332</li>
6333<li>Arguments:
6334<ul>
6335
6336<li><tt>input_object</tt> : a <tt>object</tt> value.</li>
6337<li><tt>string</tt> : a <tt>string</tt> representing the top level field name.</li>
6338</ul>
6339</li>
6340<li>Return Value:
6341<ul>
6342
6343<li>an <tt>any</tt> value saved in the designated field of the object,</li>
6344<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
6345<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6346<li>a type error will be raised if:
6347<ul>
6348
6349<li>the first argument is any other non-object value,</li>
6350<li>or, the second argument is any other non-string value.</li>
6351</ul>
6352</li>
6353</ul>
6354</li>
6355<li>
6356
6357<p>Example:</p>
6358
6359<div>
6360<div>
6361<pre class="source">get_object_field_value({
6362 &quot;id&quot;: 1,
6363 &quot;project&quot;: &quot;AsterixDB&quot;,
6364 &quot;address&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;},
6365 &quot;related&quot;: [&quot;Hivestrix&quot;, &quot;Preglix&quot;, &quot;Apache VXQuery&quot;]
6366 },
6367 &quot;project&quot;
6368 );
6369</pre></div></div>
6370</li>
6371<li>
6372
6373<p>The expected result is:</p>
6374
6375<div>
6376<div>
6377<pre class="source">&quot;AsterixDB&quot;
6378</pre></div></div>
6379</li>
6380</ul></div>
6381<div class="section">
6382<h3><a name="object_remove_fields"></a>object_remove_fields</h3>
6383<ul>
6384
6385<li>
6386
6387<p>Syntax:</p>
6388
6389<div>
6390<div>
6391<pre class="source">object_remove_fields(input_object, field_names)
6392</pre></div></div>
6393</li>
6394<li>
6395
6396<p>Remove indicated fields from a object given a list of field names.</p>
6397</li>
6398<li>Arguments:
6399<ul>
6400
6401<li><tt>input_object</tt>: a object value.</li>
6402<li><tt>field_names</tt>: an array of strings and/or array of array of strings.</li>
6403</ul>
6404</li>
6405<li>
6406
6407<p>Return Value:</p>
6408<ul>
6409
6410<li>a new object value without the fields listed in the second argument,</li>
6411<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
6412<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6413<li>a type error will be raised if:
6414<ul>
6415
6416<li>the first argument is any other non-object value,</li>
6417<li>or, the second argument is any other non-array value or recursively contains non-string items.</li>
6418</ul>
6419</li>
6420</ul>
6421</li>
6422<li>
6423
6424<p>Example:</p>
6425
6426<div>
6427<div>
6428<pre class="source">object_remove_fields(
6429 {
6430 &quot;id&quot;:1,
6431 &quot;project&quot;:&quot;AsterixDB&quot;,
6432 &quot;address&quot;:{&quot;city&quot;:&quot;Irvine&quot;, &quot;state&quot;:&quot;CA&quot;},
6433 &quot;related&quot;:[&quot;Hivestrix&quot;, &quot;Preglix&quot;, &quot;Apache VXQuery&quot;]
6434 },
6435 [[&quot;address&quot;, &quot;city&quot;], &quot;related&quot;]
6436 );
6437</pre></div></div>
6438</li>
6439<li>
6440
6441<p>The expected result is:</p>
6442
6443<div>
6444<div>
6445<pre class="source">{
6446 &quot;id&quot;:1,
6447 &quot;project&quot;:&quot;AsterixDB&quot;,
6448 &quot;address&quot;:{ &quot;state&quot;: &quot;CA&quot; }
6449}
6450</pre></div></div>
6451</li>
6452</ul></div>
6453<div class="section">
6454<h3><a name="object_add_fields"></a>object_add_fields</h3>
6455<ul>
6456
6457<li>
6458
6459<p>Syntax:</p>
6460
6461<div>
6462<div>
6463<pre class="source">object_add_fields(input_object, fields)
6464</pre></div></div>
6465</li>
6466<li>
6467
6468<p>Add fields to a object given a list of field names.</p>
6469</li>
6470<li>Arguments:
6471<ul>
6472
6473<li><tt>input_object</tt> : a object value.</li>
6474<li><tt>fields</tt>: an array of field descriptor objects where each object has field_name and field_value.</li>
6475</ul>
6476</li>
6477<li>Return Value:
6478<ul>
6479
6480<li>a new object value with the new fields included,</li>
6481<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
6482<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6483<li>a type error will be raised if:
6484<ul>
6485
6486<li>the first argument is any other non-object value,</li>
6487<li>the second argument is any other non-array value, or contains non-object items.</li>
6488</ul>
6489</li>
6490</ul>
6491</li>
6492<li>
6493
6494<p>Example:</p>
6495
6496<div>
6497<div>
6498<pre class="source">object_add_fields(
6499 {
6500 &quot;id&quot;:1,
6501 &quot;project&quot;:&quot;AsterixDB&quot;,
6502 &quot;address&quot;:{&quot;city&quot;:&quot;Irvine&quot;, &quot;state&quot;:&quot;CA&quot;},
6503 &quot;related&quot;:[&quot;Hivestrix&quot;, &quot;Preglix&quot;, &quot;Apache VXQuery&quot;]
6504 },
6505 [{&quot;field-name&quot;:&quot;employment_location&quot;, &quot;field-value&quot;:create_point(30.0,70.0)}]
6506 );
6507</pre></div></div>
6508</li>
6509<li>
6510
6511<p>The expected result is:</p>
6512
6513<div>
6514<div>
6515<pre class="source">{
6516 &quot;id&quot;:1,
6517 &quot;project&quot;:&quot;AsterixDB&quot;,
6518 &quot;address&quot;:{&quot;city&quot;:&quot;Irvine&quot;, &quot;state&quot;:&quot;CA&quot;},
6519 &quot;related&quot;:[&quot;Hivestrix&quot;, &quot;Preglix&quot;, &quot;Apache VXQuery&quot;]
6520 &quot;employment_location&quot;: point(&quot;30.0,70.0&quot;)
6521 }
6522</pre></div></div>
6523</li>
6524</ul></div>
6525<div class="section">
6526<h3><a name="object_merge"></a>object_merge</h3>
6527<ul>
6528
6529<li>
6530
6531<p>Syntax:</p>
6532
6533<div>
6534<div>
6535<pre class="source">object_merge(object1, object2)
6536</pre></div></div>
6537</li>
6538<li>
6539
6540<p>Merge two different objects into a new object.</p>
6541</li>
6542<li>Arguments:
6543<ul>
6544
6545<li><tt>object1</tt> : a object value.</li>
6546<li><tt>object2</tt> : a object value.</li>
6547</ul>
6548</li>
6549<li>Return Value:
6550<ul>
6551
6552<li>a new object value with fields from both input objects. If a field&#x2019;s names in both objects are the same, an exception is issued,</li>
6553<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
6554<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6555<li>any other non-object input value will cause a type error.</li>
6556</ul>
6557</li>
6558<li>
6559
6560<p>Example:</p>
6561
6562<div>
6563<div>
6564<pre class="source">object_merge(
6565 {
6566 &quot;id&quot;:1,
6567 &quot;project&quot;:&quot;AsterixDB&quot;,
6568 &quot;address&quot;:{&quot;city&quot;:&quot;Irvine&quot;, &quot;state&quot;:&quot;CA&quot;},
6569 &quot;related&quot;:[&quot;Hivestrix&quot;, &quot;Preglix&quot;, &quot;Apache VXQuery&quot;]
6570 },
6571 {
6572 &quot;user_id&quot;: 22,
6573 &quot;employer&quot;: &quot;UC Irvine&quot;,
6574 &quot;employment_type&quot;: &quot;visitor&quot;
6575 }
6576 );
6577</pre></div></div>
6578</li>
6579<li>
6580
6581<p>The expected result is:</p>
6582
6583<div>
6584<div>
6585<pre class="source">{
6586 &quot;employment_type&quot;: &quot;visitor&quot;,
6587 &quot;address&quot;: {
6588 &quot;city&quot;: &quot;Irvine&quot;,
6589 &quot;state&quot;: &quot;CA&quot;
6590 },
6591 &quot;related&quot;: [
6592 &quot;Hivestrix&quot;,
6593 &quot;Preglix&quot;,
6594 &quot;Apache VXQuery&quot;
6595 ],
6596 &quot;user_id&quot;: 22,
6597 &quot;project&quot;: &quot;AsterixDB&quot;,
6598 &quot;employer&quot;: &quot;UC Irvine&quot;,
6599 &quot;id&quot;: 1
6600}
6601</pre></div></div>
6602</li>
6603</ul></div>
6604<div class="section">
6605<h3><a name="object_length"></a>object_length</h3>
6606<ul>
6607
6608<li>
6609
6610<p>Syntax:</p>
6611
6612<div>
6613<div>
6614<pre class="source">object_length(input_object)
6615</pre></div></div>
6616</li>
6617<li>
6618
6619<p>Returns number of top-level fields in the given object</p>
6620</li>
6621<li>Arguments:
6622<ul>
6623
6624<li><tt>input_object</tt> : an object value.</li>
6625</ul>
6626</li>
6627<li>Return Value:
6628<ul>
6629
6630<li>an integer that represents the number of top-level fields in the given object,</li>
6631<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
6632<li><tt>null</tt> if the argument is a <tt>null</tt> value or any other non-object value</li>
6633</ul>
6634</li>
6635<li>
6636
6637<p>Example:</p>
6638
6639<div>
6640<div>
6641<pre class="source">object_length(
6642 {
6643 &quot;id&quot;: 1,
6644 &quot;project&quot;: &quot;AsterixDB&quot;,
6645 &quot;address&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;},
6646 }
6647 );
6648</pre></div></div>
6649</li>
6650<li>
6651
6652<p>The expected result is:</p>
6653
6654<div>
6655<div>
6656<pre class="source">3
6657</pre></div></div>
6658</li>
6659</ul></div>
6660<div class="section">
6661<h3><a name="object_names"></a>object_names</h3>
6662<ul>
6663
6664<li>
6665
6666<p>Syntax:</p>
6667
6668<div>
6669<div>
6670<pre class="source">object_names(input_object)
6671</pre></div></div>
6672</li>
6673<li>
6674
6675<p>Returns names of top-level fields in the given object</p>
6676</li>
6677<li>Arguments:
6678<ul>
6679
6680<li><tt>input_object</tt> : an object value.</li>
6681</ul>
6682</li>
6683<li>Return Value:
6684<ul>
6685
6686<li>an array with top-level field names of the given object,</li>
6687<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
6688<li><tt>null</tt> if the argument is a <tt>null</tt> value or any other non-object value</li>
6689</ul>
6690</li>
6691<li>
6692
6693<p>Example:</p>
6694
6695<div>
6696<div>
6697<pre class="source">object_names(
6698 {
6699 &quot;id&quot;: 1,
6700 &quot;project&quot;: &quot;AsterixDB&quot;,
6701 &quot;address&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;},
6702 }
6703 );
6704</pre></div></div>
6705</li>
6706<li>
6707
6708<p>The expected result is:</p>
6709
6710<div>
6711<div>
6712<pre class="source">[ &quot;id&quot;, &quot;project&quot;, &quot;address&quot; ]
6713</pre></div></div>
6714</li>
6715</ul></div>
6716<div class="section">
6717<h3><a name="object_remove"></a>object_remove</h3>
6718<ul>
6719
6720<li>
6721
6722<p>Syntax:</p>
6723
6724<div>
6725<div>
6726<pre class="source">object_remove(input_object, field_name)
6727</pre></div></div>
6728</li>
6729<li>
6730
6731<p>Returns a new object that has the same fields as the input object except the field to be removed</p>
6732</li>
6733<li>Arguments:
6734<ul>
6735
6736<li><tt>input_object</tt> : an object value.</li>
6737<li><tt>field_name</tt> : a string field name.</li>
6738</ul>
6739</li>
6740<li>Return Value:
6741<ul>
6742
6743<li>A new object that has the same fields as <tt>input_object</tt> except the field <tt>field_name</tt>,</li>
6744<li><tt>missing</tt> if the argument <tt>input_object</tt> or <tt>field_name</tt> is missing,</li>
6745<li><tt>null</tt> if the argument <tt>input_object</tt> is <tt>null</tt> or any other non-object value, or the argument <tt>field_name</tt> is <tt>null</tt> or any other non-string value.</li>
6746</ul>
6747</li>
6748<li>
6749
6750<p>Example:</p>
6751
6752<div>
6753<div>
6754<pre class="source">object_remove(
6755 {
6756 &quot;id&quot;: 1,
6757 &quot;project&quot;: &quot;AsterixDB&quot;,
6758 &quot;address&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;}
6759 }
6760 , &quot;address&quot;
6761 );
6762</pre></div></div>
6763</li>
6764<li>
6765
6766<p>The expected result is:</p>
6767
6768<div>
6769<div>
6770<pre class="source">{
6771 &quot;id&quot;: 1,
6772 &quot;project&quot;: &quot;AsterixDB&quot;,
6773}
6774</pre></div></div>
6775</li>
6776</ul></div>
6777<div class="section">
6778<h3><a name="object_rename"></a>object_rename</h3>
6779<ul>
6780
6781<li>
6782
6783<p>Syntax:</p>
6784
6785<div>
6786<div>
6787<pre class="source">object_rename(input_object, old_field, new_field)
6788</pre></div></div>
6789</li>
6790<li>
6791
6792<p>Returns a new object that has the same fields as <tt>input_object</tt> with field <tt>old_field</tt> replaced by <tt>new_field</tt></p>
6793</li>
6794<li>Arguments:
6795<ul>
6796
6797<li><tt>input_object</tt> : an object value.</li>
6798<li><tt>old_field</tt> : a string representing the old (original) field name inside the object <tt>input_object</tt>.</li>
6799<li><tt>new_field</tt> : a string representing the new field name to replace <tt>old_field</tt> inside the object <tt>input_object</tt>.</li>
6800</ul>
6801</li>
6802<li>Return Value:
6803<ul>
6804
6805<li>A new object that has the same fields as <tt>input_object</tt> with field <tt>old_field</tt> replaced by <tt>new_field</tt>,</li>
6806<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
6807<li><tt>null</tt> if any argument is <tt>null</tt> or <tt>input_object</tt> is non-object value, or <tt>old_field</tt> is non-string value, or <tt>new_field</tt> is any non-string value.</li>
6808</ul>
6809</li>
6810<li>
6811
6812<p>Example:</p>
6813
6814<div>
6815<div>
6816<pre class="source">object_rename(
6817 {
6818 &quot;id&quot;: 1,
6819 &quot;project&quot;: &quot;AsterixDB&quot;,
6820 &quot;address&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;}
6821 }
6822 , &quot;address&quot;
6823 , &quot;location&quot;
6824 );
6825</pre></div></div>
6826</li>
6827<li>
6828
6829<p>The expected result is:</p>
6830
6831<div>
6832<div>
6833<pre class="source">{
6834 &quot;id&quot;: 1,
6835 &quot;project&quot;: &quot;AsterixDB&quot;,
6836 &quot;location&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;}
6837}
6838</pre></div></div>
6839</li>
6840</ul></div>
6841<div class="section">
6842<h3><a name="object_wrap"></a>object_wrap</h3>
6843<ul>
6844
6845<li>
6846
6847<p>Syntax:</p>
6848
6849<div>
6850<div>
6851<pre class="source">object_wrap(input_object)
6852</pre></div></div>
6853</li>
6854<li>
6855
6856<p>Returns the value of the single name-value pair that appears in <tt>input_object</tt>.</p>
6857</li>
6858<li>Arguments:
6859<ul>
6860
6861<li><tt>input_object</tt> : an object value that consists of exactly one name-value pair.</li>
6862</ul>
6863</li>
6864<li>Return Value:
6865<ul>
6866
6867<li>The value of the single name-value pair that appears in <tt>input_object</tt>,</li>
6868<li><tt>missing</tt> if <tt>input_object</tt> is <tt>missing</tt>,</li>
6869<li><tt>null</tt> if <tt>input_object</tt> is null, or an empty object, or there is more than one name-value pair in <tt>input_object</tt>, or any non-object value.</li>
6870</ul>
6871</li>
6872<li>
6873
6874<p>Example:</p>
6875
6876<div>
6877<div>
6878<pre class="source">object_wrap(
6879 {
6880 &quot;id&quot;: 1
6881 }
6882 );
6883</pre></div></div>
6884</li>
6885<li>
6886
6887<p>The expected result is:</p>
6888
6889<div>
6890<div>
6891<pre class="source">{
6892 1
6893}
6894</pre></div></div>
6895</li>
6896</ul></div>
6897<div class="section">
6898<h3><a name="object_replace"></a>object_replace</h3>
6899<ul>
6900
6901<li>
6902
6903<p>Syntax:</p>
6904
6905<div>
6906<div>
6907<pre class="source">object_replace(input_object, old_value, new_value)
6908</pre></div></div>
6909</li>
6910<li>
6911
6912<p>Returns a new object that has the same fields as <tt>input_object</tt> with all occurrences of value <tt>old_value</tt> replaced by <tt>new_value</tt></p>
6913</li>
6914<li>Arguments:
6915<ul>
6916
6917<li><tt>input_object</tt> : an object value.</li>
6918<li><tt>old_value</tt> : a primitive type value to be replaced by <tt>new_value</tt>.</li>
6919<li><tt>new_value</tt> : a value to replace <tt>old_value</tt>.</li>
6920</ul>
6921</li>
6922<li>Return Value:
6923<ul>
6924
6925<li>A new object that has the same fields as <tt>input_object</tt> with all occurrences of value <tt>old_value</tt> replaced by <tt>new_value</tt>,</li>
6926<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
6927<li><tt>null</tt> if <tt>input_object</tt> or <tt>old_value</tt> is null,</li>
6928<li>a type error will be raised if:
6929<ul>
6930
6931<li><tt>old_value</tt> is not a primitive type value.</li>
6932</ul>
6933</li>
6934</ul>
6935</li>
6936<li>
6937
6938<p>Example:</p>
6939
6940<div>
6941<div>
6942<pre class="source">object_replace(
6943 {
6944 &quot;id&quot;: 1,
6945 &quot;project&quot;: &quot;AsterixDB&quot;,
6946 &quot;address&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;}
6947 }
6948 , &quot;AsterixDB&quot;
6949 , &quot;Apache AsterixDB&quot;
6950 );
6951</pre></div></div>
6952</li>
6953<li>
6954
6955<p>The expected result is:</p>
6956
6957<div>
6958<div>
6959<pre class="source">{
6960 &quot;id&quot;: 1,
6961 &quot;project&quot;: &quot;Apache AsterixDB&quot;,
6962 &quot;location&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;}
6963}
6964</pre></div></div>
6965</li>
6966</ul></div>
6967<div class="section">
6968<h3><a name="object_add"></a>object_add</h3>
6969<ul>
6970
6971<li>
6972
6973<p>Syntax:</p>
6974
6975<div>
6976<div>
6977<pre class="source">object_add(input_object, field_name, field_value)
6978</pre></div></div>
6979</li>
6980<li>
6981
6982<p>Returns a new object that has the same fields as <tt>input_object</tt> as well as the new field <tt>field_name</tt>.</p>
6983</li>
6984<li>Arguments:
6985<ul>
6986
6987<li><tt>input_object</tt> : an object value.</li>
6988<li><tt>field_name</tt> : a string representing a field name to be added.</li>
6989<li><tt>field_value</tt> : a value to be assigned to the new field <tt>field_name</tt>.</li>
6990</ul>
6991</li>
6992<li>Return Value:
6993<ul>
6994
6995<li>A new object that has the same fields as <tt>input_object</tt> as well as the new field <tt>field_name</tt>,</li>
6996<li><tt>missing</tt> if <tt>input_object</tt> or <tt>field_name</tt> is <tt>missing</tt>,</li>
6997<li><tt>null</tt> if <tt>input_object</tt> or <tt>field_name</tt> is <tt>null</tt>, or <tt>input_object</tt> is not an object, or <tt>field_name</tt> is not a string,</li>
6998<li><tt>input_object</tt> if <tt>field_name</tt>already exists in <tt>input_object</tt> or <tt>field_value</tt> is missing.</li>
6999</ul>
7000</li>
7001<li>
7002
7003<p>Example:</p>
7004
7005<div>
7006<div>
7007<pre class="source">object_add(
7008 {
7009 &quot;id&quot;: 1,
7010 &quot;project&quot;: &quot;AsterixDB&quot;,
7011 &quot;address&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;}
7012 }
7013 , &quot;company&quot;
7014 , &quot;Apache&quot;
7015 );
7016</pre></div></div>
7017</li>
7018<li>
7019
7020<p>The expected result is:</p>
7021
7022<div>
7023<div>
7024<pre class="source">{
7025 &quot;id&quot;: 1,
7026 &quot;project&quot;: &quot;AsterixDB&quot;,
7027 &quot;location&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;},
7028 &quot;company&quot;: &quot;Apache&quot;
7029}
7030</pre></div></div>
7031</li>
7032</ul></div>
7033<div class="section">
7034<h3><a name="object_put"></a>object_put</h3>
7035<ul>
7036
7037<li>
7038
7039<p>Syntax:</p>
7040
7041<div>
7042<div>
7043<pre class="source">object_put(input_object, field_name, field_value)
7044</pre></div></div>
7045</li>
7046<li>
7047
7048<p>Adds, modifies, or removes a field of an object.</p>
7049</li>
7050<li>Arguments:
7051<ul>
7052
7053<li><tt>input_object</tt> : an object value.</li>
7054<li><tt>field_name</tt> : a string representing a field name to be added.</li>
7055<li><tt>field_value</tt> : a value to be assigned to the new field <tt>field_name</tt>.</li>
7056</ul>
7057</li>
7058<li>Return Value:
7059<ul>
7060
7061<li>a new object that has the same fields as <tt>input_object</tt> as well as the new field <tt>field_name</tt>, or with updated <tt>field_name</tt> value to <tt>field_value</tt> if <tt>field_name</tt> already exists in <tt>input_object</tt>, or with <tt>field_name</tt>removed if <tt>field_name</tt> already exists in <tt>input_object</tt> and <tt>field_value</tt> is <tt>missing</tt>,</li>
7062<li><tt>missing</tt> if <tt>input_object</tt> or <tt>field_name</tt> is <tt>missing</tt>,</li>
7063<li><tt>null</tt> if <tt>input_object</tt> or <tt>field_name</tt> is <tt>null</tt>, or <tt>input_object</tt> is not an object, or <tt>field_name</tt> is not not a string.</li>
7064</ul>
7065</li>
7066<li>
7067
7068<p>Example:</p>
7069
7070<div>
7071<div>
7072<pre class="source">object_put(
7073 {
7074 &quot;id&quot;: 1,
7075 &quot;project&quot;: &quot;AsterixDB&quot;,
7076 &quot;address&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;}
7077 }
7078 , &quot;project&quot;
7079 , &quot;Apache AsterixDB&quot;
7080 );
7081</pre></div></div>
7082</li>
7083<li>
7084
7085<p>The expected result is:</p>
7086
7087<div>
7088<div>
7089<pre class="source">{
7090 &quot;id&quot;: 1,
7091 &quot;project&quot;: &quot;Apache AsterixDB&quot;,
7092 &quot;location&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;}
7093}
7094</pre></div></div>
7095</li>
7096</ul></div>
7097<div class="section">
7098<h3><a name="object_values"></a>object_values</h3>
7099<ul>
7100
7101<li>
7102
7103<p>Syntax:</p>
7104
7105<div>
7106<div>
7107<pre class="source">object_values(input_object)
7108</pre></div></div>
7109</li>
7110<li>
7111
7112<p>Returns an array of the values of the fields in <tt>input_object</tt>.</p>
7113</li>
7114<li>Arguments:
7115<ul>
7116
7117<li><tt>input_object</tt> : an object value.</li>
7118</ul>
7119</li>
7120<li>Return Value:
7121<ul>
7122
7123<li>An array of the values of the fields in <tt>input_object</tt>,</li>
7124<li><tt>missing</tt> if <tt>input_object</tt> is <tt>missing</tt>,</li>
7125<li><tt>null</tt> if <tt>input_object</tt> is null or any non-object value.</li>
7126</ul>
7127</li>
7128<li>
7129
7130<p>Example:</p>
7131
7132<div>
7133<div>
7134<pre class="source">object_values(
7135 {
7136 &quot;id&quot;: 1,
7137 &quot;project&quot;: &quot;AsterixDB&quot;,
7138 &quot;address&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;}
7139 }
7140 );
7141</pre></div></div>
7142</li>
7143<li>
7144
7145<p>The expected result is:</p>
7146
7147<div>
7148<div>
7149<pre class="source">[
7150 1,
7151 &quot;AsterixDB&quot;,
7152 {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;}
7153]
7154</pre></div></div>
7155</li>
7156</ul></div>
7157<div class="section">
7158<h3><a name="object_pairs"></a>object_pairs</h3>
7159<ul>
7160
7161<li>
7162
7163<p>Syntax:</p>
7164
7165<div>
7166<div>
7167<pre class="source">object_pairs(input_object)
7168</pre></div></div>
7169</li>
7170<li>
7171
7172<p>Returns an array of objects describing fields of <tt>input_object</tt>. For each field of the <tt>input_object</tt> the returned array contains an object with two fields <tt>name</tt> and <tt>value</tt> which are set to the <tt>input_object</tt>&#x2019;s field name and value.</p>
7173</li>
7174<li>
7175
7176<p>Arguments:</p>
7177<ul>
7178
7179<li><tt>input_object</tt> : an object value.</li>
7180</ul>
7181</li>
7182<li>Return Value:
7183<ul>
7184
7185<li>An array of the <tt>name</tt>/<tt>value</tt> pairs of the fields in <tt>input_object</tt>,</li>
7186<li><tt>missing</tt> if <tt>input_object</tt> is <tt>missing</tt>,</li>
7187<li><tt>null</tt> if <tt>input_object</tt> is null or any non-object value.</li>
7188</ul>
7189</li>
7190<li>
7191
7192<p>Example:</p>
7193
7194<div>
7195<div>
7196<pre class="source">object_pairs(
7197 {
7198 &quot;id&quot;: 1,
7199 &quot;project&quot;: &quot;AsterixDB&quot;,
7200 &quot;address&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;}
7201 }
7202 );
7203</pre></div></div>
7204</li>
7205<li>
7206
7207<p>The expected result is:</p>
7208
7209<div>
7210<div>
7211<pre class="source">[
7212 { &quot;name&quot;: &quot;id&quot;, &quot;value&quot;: 1 },
7213 { &quot;name&quot;: &quot;project&quot;, &quot;value&quot;: &quot;AsterixDB&quot; },
7214 { &quot;name&quot;: &quot;address&quot;, &quot;value&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;} }
7215]
7216</pre></div></div>
7217</li>
7218</ul></div>
7219<div class="section">
7220<h3><a name="pairs"></a>pairs</h3>
7221<ul>
7222
7223<li>
7224
7225<p>Syntax:</p>
7226
7227<div>
7228<div>
7229<pre class="source">pairs(input_object)
7230</pre></div></div>
7231</li>
7232<li>
7233
7234<p>Returns an array of arrays describing fields of <tt>input_object</tt>, including nested fields. For each field of the <tt>input_object</tt> the returned array contains an array with two elements. The first element is the name and the second one is the value of the <tt>input_object</tt>&#x2019;s field. The input object is introspected recursively, so all fields of its nested objects are returned. Nested objects contained in arrays and multisets are also processed by this function.</p>
7235</li>
7236<li>
7237
7238<p>Arguments:</p>
7239<ul>
7240
7241<li><tt>input_object</tt> : an object value (or an array or a multiset)</li>
7242</ul>
7243</li>
7244<li>Return Value:
7245<ul>
7246
7247<li>An array of arrays with name, value pairs of the fields in <tt>input_object</tt>, including nested fields. Each inner array has exactly two items: name and value of the <tt>input_object</tt>&#x2019;s field.</li>
7248<li><tt>missing</tt> if <tt>input_object</tt> is <tt>missing</tt>,</li>
7249<li><tt>null</tt> if <tt>input_object</tt> is null or a value of a primitive data type.</li>
7250</ul>
7251</li>
7252<li>
7253
7254<p>Example:</p>
7255
7256<div>
7257<div>
7258<pre class="source">pairs(
7259 {
7260 &quot;id&quot;: 1,
7261 &quot;project&quot;: &quot;AsterixDB&quot;,
7262 &quot;address&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;}
7263 }
7264 );
7265</pre></div></div>
7266</li>
7267<li>
7268
7269<p>The expected result is:</p>
7270
7271<div>
7272<div>
7273<pre class="source">[
7274 [ &quot;id&quot;, 1 ],
7275 [ &quot;project&quot;, &quot;AsterixDB&quot; ],
7276 [ &quot;address&quot;, { &quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot; } ],
7277 [ &quot;city&quot;, &quot;Irvine&quot; ],
7278 [ &quot;state&quot;, &quot;CA&quot; ]
7279]
7280</pre></div></div>
7281</li>
7282</ul><!--
7283 ! Licensed to the Apache Software Foundation (ASF) under one
7284 ! or more contributor license agreements. See the NOTICE file
7285 ! distributed with this work for additional information
7286 ! regarding copyright ownership. The ASF licenses this file
7287 ! to you under the Apache License, Version 2.0 (the
7288 ! "License"); you may not use this file except in compliance
7289 ! with the License. You may obtain a copy of the License at
7290 !
7291 ! http://www.apache.org/licenses/LICENSE-2.0
7292 !
7293 ! Unless required by applicable law or agreed to in writing,
7294 ! software distributed under the License is distributed on an
7295 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
7296 ! KIND, either express or implied. See the License for the
7297 ! specific language governing permissions and limitations
7298 ! under the License.
7299 !-->
7300</div></div>
7301<div class="section">
7302<h2><a name="Aggregate_Functions_.28Array_Functions.29"></a><a name="AggregateFunctions" id="AggregateFunctions">Aggregate Functions (Array Functions) </a></h2>
7303<p>This section contains detailed descriptions of each SQL++ aggregate function (i.e., array function). Note that as described in the SQL++ query reference documentation, standard SQL aggregate functions (e.g., <tt>MIN</tt>, <tt>MAX</tt>, <tt>SUM</tt>, <tt>COUNT</tt>, and <tt>AVG</tt>) are not real functions in SQL++ but just syntactic sugars over corresponding SQL++ builtin aggregate functions (e.g., <tt>ARRAY_MIN</tt>, <tt>ARRAY_MAX</tt>, <tt>ARRAY_SUM</tt>, <tt>ARRAY_COUNT</tt>, and <tt>ARRAY_AVG</tt>).</p>
7304<div class="section">
7305<h3><a name="array_count"></a>array_count</h3>
7306<ul>
7307
7308<li>
7309
7310<p>Syntax:</p>
7311
7312<div>
7313<div>
7314<pre class="source">array_count(collection)
7315</pre></div></div>
7316</li>
7317<li>
7318
7319<p>Gets the number of non-null and non-missing items in the given collection.</p>
7320</li>
7321<li>Arguments:
7322<ul>
7323
7324<li><tt>collection</tt> could be:
7325<ul>
7326
7327<li>an <tt>array</tt> or <tt>multiset</tt> to be counted,</li>
7328<li>or, a <tt>null</tt> value,</li>
7329<li>or, a <tt>missing</tt> value.</li>
7330</ul>
7331</li>
7332</ul>
7333</li>
7334<li>Return Value:
7335<ul>
7336
7337<li>a <tt>bigint</tt> value representing the number of non-null and non-missing items in the given collection,</li>
7338<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
7339<li>any other non-array and non-multiset input value will cause an error.</li>
7340</ul>
7341</li>
7342<li>
7343
7344<p>Example:</p>
7345
7346<div>
7347<div>
7348<pre class="source">array_count( ['hello', 'world', 1, 2, 3, null, missing] );
7349</pre></div></div>
7350</li>
7351<li>
7352
7353<p>The expected result is:</p>
7354
7355<div>
7356<div>
7357<pre class="source">5
7358</pre></div></div>
7359</li>
7360</ul></div>
7361<div class="section">
7362<h3><a name="array_avg"></a>array_avg</h3>
7363<ul>
7364
7365<li>
7366
7367<p>Syntax:</p>
7368
7369<div>
7370<div>
7371<pre class="source">array_avg(num_collection)
7372</pre></div></div>
7373</li>
7374<li>
7375
7376<p>Gets the average value of the non-null and non-missing numeric items in the given collection.</p>
7377</li>
7378<li>Arguments:
7379<ul>
7380
7381<li><tt>num_collection</tt> could be:
7382<ul>
7383
7384<li>an <tt>array</tt> or <tt>multiset</tt> containing numeric values, <tt>null</tt>s or <tt>missing</tt>s,</li>
7385<li>or, a <tt>null</tt> value,</li>
7386<li>or, a <tt>missing</tt> value.</li>
7387</ul>
7388</li>
7389</ul>
7390</li>
7391<li>Return Value:
7392<ul>
7393
7394<li>a <tt>double</tt> value representing the average of the non-null and non-missing numbers in the given collection,</li>
7395<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
7396<li><tt>null</tt> is returned if the given collection does not contain any non-null and non-missing items,</li>
7397<li>any other non-array and non-multiset input value will cause a type error,</li>
7398<li>any other non-numeric value in the input collection will cause a type error.</li>
7399</ul>
7400</li>
7401<li>
7402
7403<p>Example:</p>
7404
7405<div>
7406<div>
7407<pre class="source">array_avg( [1.2, 2.3, 3.4, 0, null] );
7408</pre></div></div>
7409</li>
7410<li>
7411
7412<p>The expected result is:</p>
7413
7414<div>
7415<div>
7416<pre class="source">1.725
7417</pre></div></div>
7418</li>
7419</ul></div>
7420<div class="section">
7421<h3><a name="array_sum"></a>array_sum</h3>
7422<ul>
7423
7424<li>
7425
7426<p>Syntax:</p>
7427
7428<div>
7429<div>
7430<pre class="source">array_sum(num_collection)
7431</pre></div></div>
7432</li>
7433<li>
7434
7435<p>Gets the sum of non-null and non-missing items in the given collection.</p>
7436</li>
7437<li>Arguments:
7438<ul>
7439
7440<li><tt>num_collection</tt> could be:
7441<ul>
7442
7443<li>an <tt>array</tt> or <tt>multiset</tt> containing numeric values, <tt>null</tt>s or <tt>missing</tt>s,</li>
7444<li>or, a <tt>null</tt> value,</li>
7445<li>or, a <tt>missing</tt> value.</li>
7446</ul>
7447</li>
7448</ul>
7449</li>
7450<li>Return Value:
7451<ul>
7452
7453<li>the sum of the non-null and non-missing numbers in the given collection. The returning type is decided by the item type with the highest order in the numeric type promotion order (<tt>tinyint</tt>-&gt; <tt>smallint</tt>-&gt;<tt>integer</tt>-&gt;<tt>bigint</tt>-&gt;<tt>float</tt>-&gt;<tt>double</tt>) among items.</li>
7454<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
7455<li><tt>null</tt> is returned if the given collection does not contain any non-null and non-missing items,</li>
7456<li>any other non-array and non-multiset input value will cause a type error,</li>
7457<li>any other non-numeric value in the input collection will cause a type error.</li>
7458</ul>
7459</li>
7460<li>
7461
7462<p>Example:</p>
7463
7464<div>
7465<div>
7466<pre class="source">array_sum( [1.2, 2.3, 3.4, 0, null, missing] );
7467</pre></div></div>
7468</li>
7469<li>
7470
7471<p>The expected result is:</p>
7472
7473<div>
7474<div>
7475<pre class="source">6.9
7476</pre></div></div>
7477</li>
7478</ul></div>
7479<div class="section">
7480<h3><a name="array_sql_min"></a>array_sql_min</h3>
7481<ul>
7482
7483<li>
7484
7485<p>Syntax:</p>
7486
7487<div>
7488<div>
7489<pre class="source">array_min(num_collection)
7490</pre></div></div>
7491</li>
7492<li>
7493
7494<p>Gets the min value of non-null and non-missing comparable items in the given collection.</p>
7495</li>
7496<li>Arguments:
7497<ul>
7498
7499<li><tt>num_collection</tt> could be:
7500<ul>
7501
7502<li>an <tt>array</tt> or <tt>multiset</tt>,</li>
7503<li>or, a <tt>null</tt> value,</li>
7504<li>or, a <tt>missing</tt> value.</li>
7505</ul>
7506</li>
7507</ul>
7508</li>
7509<li>Return Value:
7510<ul>
7511
7512<li>the min value of non-null and non-missing values in the given collection. The returning type is decided by the item type with the highest order in the type promotion order (<tt>tinyint</tt>-&gt; <tt>smallint</tt>-&gt;<tt>integer</tt>-&gt;<tt>bigint</tt>-&gt;<tt>float</tt>-&gt;<tt>double</tt>) among numeric items.</li>
7513<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
7514<li><tt>null</tt> is returned if the given collection does not contain any non-null and non-missing items,</li>
7515<li>multiple incomparable items in the input array or multiset will cause a type error,</li>
7516<li>any other non-array and non-multiset input value will cause a type error.</li>
7517</ul>
7518</li>
7519<li>
7520
7521<p>Example:</p>
7522
7523<div>
7524<div>
7525<pre class="source">array_min( [1.2, 2.3, 3.4, 0, null, missing] );
7526</pre></div></div>
7527</li>
7528<li>
7529
7530<p>The expected result is:</p>
7531
7532<div>
7533<div>
7534<pre class="source">0.0
7535</pre></div></div>
7536</li>
7537</ul></div>
7538<div class="section">
7539<h3><a name="array_max"></a>array_max</h3>
7540<ul>
7541
7542<li>
7543
7544<p>Syntax:</p>
7545
7546<div>
7547<div>
7548<pre class="source">array_max(num_collection)
7549</pre></div></div>
7550</li>
7551<li>
7552
7553<p>Gets the max value of the non-null and non-missing comparable items in the given collection.</p>
7554</li>
7555<li>Arguments:
7556<ul>
7557
7558<li><tt>num_collection</tt> could be:
7559<ul>
7560
7561<li>an <tt>array</tt> or <tt>multiset</tt>,</li>
7562<li>or, a <tt>null</tt> value,</li>
7563<li>or, a <tt>missing</tt> value.</li>
7564</ul>
7565</li>
7566</ul>
7567</li>
7568<li>Return Value:
7569<ul>
7570
7571<li>the max value of non-null and non-missing numbers in the given collection. The returning type is decided by the item type with the highest order in the type promotion order (<tt>tinyint</tt>-&gt; <tt>smallint</tt>-&gt;<tt>integer</tt>-&gt;<tt>bigint</tt>-&gt;<tt>float</tt>-&gt;<tt>double</tt>) among numeric items.</li>
7572<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
7573<li><tt>null</tt> is returned if the given collection does not contain any non-null and non-missing items,</li>
7574<li>multiple incomparable items in the input array or multiset will cause a type error,</li>
7575<li>any other non-array and non-multiset input value will cause a type error.</li>
7576</ul>
7577</li>
7578<li>
7579
7580<p>Example:</p>
7581
7582<div>
7583<div>
7584<pre class="source">array_max( [1.2, 2.3, 3.4, 0, null, missing] );
7585</pre></div></div>
7586</li>
7587<li>
7588
7589<p>The expected result is:</p>
7590
7591<div>
7592<div>
7593<pre class="source">3.4
7594</pre></div></div>
7595</li>
7596</ul></div>
7597<div class="section">
7598<h3><a name="strict_count"></a>strict_count</h3>
7599<ul>
7600
7601<li>
7602
7603<p>Syntax:</p>
7604
7605<div>
7606<div>
7607<pre class="source">strict_count(collection)
7608</pre></div></div>
7609</li>
7610<li>
7611
7612<p>Gets the number of items in the given collection.</p>
7613</li>
7614<li>Arguments:
7615<ul>
7616
7617<li><tt>collection</tt> could be:
7618<ul>
7619
7620<li>an <tt>array</tt> or <tt>multiset</tt> containing the items to be counted,</li>
7621<li>or a <tt>null</tt> value,</li>
7622<li>or a <tt>missing</tt> value.</li>
7623</ul>
7624</li>
7625</ul>
7626</li>
7627<li>Return Value:
7628<ul>
7629
7630<li>a <tt>bigint</tt> value representing the number of items in the given collection,</li>
7631<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>.</li>
7632</ul>
7633</li>
7634<li>
7635
7636<p>Example:</p>
7637
7638<div>
7639<div>
7640<pre class="source">strict_count( [1, 2, null, missing] );
7641</pre></div></div>
7642</li>
7643<li>
7644
7645<p>The expected result is:</p>
7646
7647<div>
7648<div>
7649<pre class="source">4
7650</pre></div></div>
7651</li>
7652</ul></div>
7653<div class="section">
7654<h3><a name="strict_avg"></a>strict_avg</h3>
7655<ul>
7656
7657<li>
7658
7659<p>Syntax:</p>
7660
7661<div>
7662<div>
7663<pre class="source">strict_avg(num_collection)
7664</pre></div></div>
7665</li>
7666<li>
7667
7668<p>Gets the average value of the numeric items in the given collection.</p>
7669</li>
7670<li>Arguments:
7671<ul>
7672
7673<li><tt>num_collection</tt> could be:
7674<ul>
7675
7676<li>an <tt>array</tt> or <tt>multiset</tt> containing numeric values, <tt>null</tt>s or <tt>missing</tt>s,</li>
7677<li>or, a <tt>null</tt> value,</li>
7678<li>or, a <tt>missing</tt> value.</li>
7679</ul>
7680</li>
7681</ul>
7682</li>
7683<li>Return Value:
7684<ul>
7685
7686<li>a <tt>double</tt> value representing the average of the numbers in the given collection,</li>
7687<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
7688<li><tt>null</tt> is returned if there is a <tt>null</tt> or <tt>missing</tt> in the input collection,</li>
7689<li>any other non-numeric value in the input collection will cause a type error.</li>
7690</ul>
7691</li>
7692<li>
7693
7694<p>Example:</p>
7695
7696<div>
7697<div>
7698<pre class="source">strict_avg( [100, 200, 300] );
7699</pre></div></div>
7700</li>
7701<li>
7702
7703<p>The expected result is:</p>
7704
7705<div>
7706<div>
7707<pre class="source">[ 200.0 ]
7708</pre></div></div>
7709</li>
7710</ul></div>
7711<div class="section">
7712<h3><a name="strict_sum"></a>strict_sum</h3>
7713<ul>
7714
7715<li>
7716
7717<p>Syntax:</p>
7718
7719<div>
7720<div>
7721<pre class="source">strict_sum(num_collection)
7722</pre></div></div>
7723</li>
7724<li>
7725
7726<p>Gets the sum of the items in the given collection.</p>
7727</li>
7728<li>Arguments:
7729<ul>
7730
7731<li><tt>num_collection</tt> could be:
7732<ul>
7733
7734<li>an <tt>array</tt> or <tt>multiset</tt> containing numeric values, <tt>null</tt>s or <tt>missing</tt>s,</li>
7735<li>or, a <tt>null</tt> value,</li>
7736<li>or, a <tt>missing</tt> value.</li>
7737</ul>
7738</li>
7739</ul>
7740</li>
7741<li>Return Value:
7742<ul>
7743
7744<li>the sum of the numbers in the given collection. The returning type is decided by the item type with the highest order in the numeric type promotion order (<tt>tinyint</tt>-&gt; <tt>smallint</tt>-&gt;<tt>integer</tt>-&gt;<tt>bigint</tt>-&gt;<tt>float</tt>-&gt;<tt>double</tt>) among items.</li>
7745<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
7746<li><tt>null</tt> is returned if there is a <tt>null</tt> or <tt>missing</tt> in the input collection,</li>
7747<li>any other non-numeric value in the input collection will cause a type error.</li>
7748</ul>
7749</li>
7750<li>
7751
7752<p>Example:</p>
7753
7754<div>
7755<div>
7756<pre class="source">strict_sum( [100, 200, 300] );
7757</pre></div></div>
7758</li>
7759<li>
7760
7761<p>The expected result is:</p>
7762
7763<div>
7764<div>
7765<pre class="source">600
7766</pre></div></div>
7767</li>
7768</ul></div>
7769<div class="section">
7770<h3><a name="array_min"></a>array_min</h3>
7771<ul>
7772
7773<li>
7774
7775<p>Syntax:</p>
7776
7777<div>
7778<div>
7779<pre class="source">strict_min(num_collection)
7780</pre></div></div>
7781</li>
7782<li>
7783
7784<p>Gets the min value of comparable items in the given collection.</p>
7785</li>
7786<li>Arguments:
7787<ul>
7788
7789<li><tt>num_collection</tt> could be:
7790<ul>
7791
7792<li>an <tt>array</tt> or <tt>multiset</tt>,</li>
7793<li>or, a <tt>null</tt> value,</li>
7794<li>or, a <tt>missing</tt> value.</li>
7795</ul>
7796</li>
7797</ul>
7798</li>
7799<li>Return Value:
7800<ul>
7801
7802<li>the min value of the given collection. The returning type is decided by the item type with the highest order in the type promotion order (<tt>tinyint</tt>-&gt; <tt>smallint</tt>-&gt;<tt>integer</tt>-&gt;<tt>bigint</tt>-&gt;<tt>float</tt>-&gt;<tt>double</tt>) among numeric items.</li>
7803<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
7804<li><tt>null</tt> is returned if there is a <tt>null</tt> or <tt>missing</tt> in the input collection,</li>
7805<li>multiple incomparable items in the input array or multiset will cause a type error,</li>
7806<li>any other non-array and non-multiset input value will cause a type error.</li>
7807</ul>
7808</li>
7809<li>
7810
7811<p>Example:</p>
7812
7813<div>
7814<div>
7815<pre class="source">strict_min( [10.2, 100, 5] );
7816</pre></div></div>
7817</li>
7818<li>
7819
7820<p>The expected result is:</p>
7821
7822<div>
7823<div>
7824<pre class="source">5.0
7825</pre></div></div>
7826</li>
7827</ul></div>
7828<div class="section">
7829<h3><a name="array_max"></a>array_max</h3>
7830<ul>
7831
7832<li>
7833
7834<p>Syntax:</p>
7835
7836<div>
7837<div>
7838<pre class="source">strict_max(num_collection)
7839</pre></div></div>
7840</li>
7841<li>
7842
7843<p>Gets the max value of numeric items in the given collection.</p>
7844</li>
7845<li>Arguments:
7846<ul>
7847
7848<li><tt>num_collection</tt> could be:
7849<ul>
7850
7851<li>an <tt>array</tt> or <tt>multiset</tt>,</li>
7852<li>or, a <tt>null</tt> value,</li>
7853<li>or, a <tt>missing</tt> value.</li>
7854</ul>
7855</li>
7856</ul>
7857</li>
7858<li>Return Value:
7859<ul>
7860
7861<li>The max value of the given collection. The returning type is decided by the item type with the highest order in the type promotion order (<tt>tinyint</tt>-&gt; <tt>smallint</tt>-&gt;<tt>integer</tt>-&gt;<tt>bigint</tt>-&gt;<tt>float</tt>-&gt;<tt>double</tt>) among numeric items.</li>
7862<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
7863<li><tt>null</tt> is returned if there is a <tt>null</tt> or <tt>missing</tt> in the input collection,</li>
7864<li>multiple incomparable items in the input array or multiset will cause a type error,</li>
7865<li>any other non-array and non-multiset input value will cause a type error.</li>
7866</ul>
7867</li>
7868<li>
7869
7870<p>Example:</p>
7871
7872<div>
7873<div>
7874<pre class="source">strict_max( [10.2, 100, 5] );
7875</pre></div></div>
7876</li>
7877<li>
7878
7879<p>The expected result is:</p>
7880
7881<div>
7882<div>
7883<pre class="source">100.0
7884</pre></div></div>
7885</li>
7886</ul><!--
7887 ! Licensed to the Apache Software Foundation (ASF) under one
7888 ! or more contributor license agreements. See the NOTICE file
7889 ! distributed with this work for additional information
7890 ! regarding copyright ownership. The ASF licenses this file
7891 ! to you under the Apache License, Version 2.0 (the
7892 ! "License"); you may not use this file except in compliance
7893 ! with the License. You may obtain a copy of the License at
7894 !
7895 ! http://www.apache.org/licenses/LICENSE-2.0
7896 !
7897 ! Unless required by applicable law or agreed to in writing,
7898 ! software distributed under the License is distributed on an
7899 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
7900 ! KIND, either express or implied. See the License for the
7901 ! specific language governing permissions and limitations
7902 ! under the License.
7903 !-->
7904</div></div>
7905<div class="section">
7906<h2><a name="Comparison_Functions"></a><a name="ComparisonFunctions" id="ComparisonFunctions">Comparison Functions</a></h2>
7907<div class="section">
7908<h3><a name="greatest"></a>greatest</h3>
7909<ul>
7910
7911<li>
7912
7913<p>Syntax:</p>
7914
7915<div>
7916<div>
7917<pre class="source">greatest(numeric_value1, numeric_value2, ...)
7918</pre></div></div>
7919</li>
7920<li>
7921
7922<p>Computes the greatest value among arguments.</p>
7923</li>
7924<li>Arguments:
7925<ul>
7926
7927<li><tt>numeric_value1</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value,</li>
7928<li><tt>numeric_value2</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value,</li>
7929<li>&#x2026;.</li>
7930</ul>
7931</li>
7932<li>Return Value:
7933<ul>
7934
7935<li>the greatest values among arguments. The returning type is decided by the item type with the highest order in the numeric type promotion order (<tt>tinyint</tt>-&gt; <tt>smallint</tt>-&gt;<tt>integer</tt>-&gt;<tt>bigint</tt>-&gt;<tt>float</tt>-&gt;<tt>double</tt>) among items.</li>
7936<li><tt>null</tt> if any argument is a <tt>missing</tt> value or <tt>null</tt> value,</li>
7937<li>any other non-numeric input value will cause a type error.</li>
7938</ul>
7939</li>
7940<li>
7941
7942<p>Example:</p>
7943
7944<div>
7945<div>
7946<pre class="source">{ &quot;v1&quot;: greatest(1, 2, 3), &quot;v2&quot;: greatest(float(&quot;0.5&quot;), double(&quot;-0.5&quot;), 5000) };
7947</pre></div></div>
7948</li>
7949<li>
7950
7951<p>The expected result is:</p>
7952
7953<div>
7954<div>
7955<pre class="source">{ &quot;v1&quot;: 3, &quot;v2&quot;: 5000.0 }
7956</pre></div></div>
7957</li>
7958</ul></div>
7959<div class="section">
7960<h3><a name="least"></a>least</h3>
7961<ul>
7962
7963<li>
7964
7965<p>Syntax:</p>
7966
7967<div>
7968<div>
7969<pre class="source">least(numeric_value1, numeric_value2, ...)
7970</pre></div></div>
7971</li>
7972<li>
7973
7974<p>Computes the least value among arguments.</p>
7975</li>
7976<li>Arguments:
7977<ul>
7978
7979<li><tt>numeric_value1</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value,</li>
7980<li><tt>numeric_value2</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value,</li>
7981<li>&#x2026;.</li>
7982</ul>
7983</li>
7984<li>Return Value:
7985<ul>
7986
7987<li>the least values among arguments. The returning type is decided by the item type with the highest order in the numeric type promotion order (<tt>tinyint</tt>-&gt; <tt>smallint</tt>-&gt;<tt>integer</tt>-&gt;<tt>bigint</tt>-&gt;<tt>float</tt>-&gt;<tt>double</tt>) among items.</li>
7988<li><tt>null</tt> if any argument is a <tt>missing</tt> value or <tt>null</tt> value,</li>
7989<li>any other non-numeric input value will cause a type error.</li>
7990</ul>
7991</li>
7992<li>
7993
7994<p>Example:</p>
7995
7996<div>
7997<div>
7998<pre class="source">{ &quot;v1&quot;: least(1, 2, 3), &quot;v2&quot;: least(float(&quot;0.5&quot;), double(&quot;-0.5&quot;), 5000) };
7999</pre></div></div>
8000</li>
8001<li>
8002
8003<p>The expected result is:</p>
8004
8005<div>
8006<div>
8007<pre class="source">{ &quot;v1&quot;: 1, &quot;v2&quot;: -0.5 }
8008</pre></div></div>
8009</li>
8010</ul><!--
8011 ! Licensed to the Apache Software Foundation (ASF) under one
8012 ! or more contributor license agreements. See the NOTICE file
8013 ! distributed with this work for additional information
8014 ! regarding copyright ownership. The ASF licenses this file
8015 ! to you under the Apache License, Version 2.0 (the
8016 ! "License"); you may not use this file except in compliance
8017 ! with the License. You may obtain a copy of the License at
8018 !
8019 ! http://www.apache.org/licenses/LICENSE-2.0
8020 !
8021 ! Unless required by applicable law or agreed to in writing,
8022 ! software distributed under the License is distributed on an
8023 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
8024 ! KIND, either express or implied. See the License for the
8025 ! specific language governing permissions and limitations
8026 ! under the License.
8027 !-->
8028</div></div>
8029<div class="section">
8030<h2><a name="Type_Functions"></a><a name="TypeFunctions" id="TypeFunctions">Type Functions</a></h2>
8031<div class="section">
8032<h3><a name="is_array"></a>is_array</h3>
8033<ul>
8034
8035<li>
8036
8037<p>Syntax:</p>
8038
8039<div>
8040<div>
8041<pre class="source">is_array(expr)
8042</pre></div></div>
8043</li>
8044<li>
8045
8046<p>Checks whether the given expression is evaluated to be an <tt>array</tt> value.</p>
8047</li>
8048<li>Arguments:
8049<ul>
8050
8051<li><tt>expr</tt> : an expression (any type is allowed).</li>
8052</ul>
8053</li>
8054<li>Return Value:
8055<ul>
8056
8057<li>a <tt>boolean</tt> on whether the argument is an <tt>array</tt> value or not,</li>
8058<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
8059<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
8060</ul>
8061</li>
8062<li>
8063
8064<p>Example:</p>
8065
8066<div>
8067<div>
8068<pre class="source">{
8069 &quot;a&quot;: is_array(true),
8070 &quot;b&quot;: is_array(false),
8071 &quot;c&quot;: isarray(null),
8072 &quot;d&quot;: isarray(missing),
8073 &quot;e&quot;: isarray(&quot;d&quot;),
8074 &quot;f&quot;: isarray(4.0),
8075 &quot;g&quot;: isarray(5),
8076 &quot;h&quot;: isarray([&quot;1&quot;, 2]),
8077 &quot;i&quot;: isarray({&quot;a&quot;:1})
8078};
8079</pre></div></div>
8080</li>
8081<li>
8082
8083<p>The expected result is:</p>
8084
8085<div>
8086<div>
8087<pre class="source">{ &quot;a&quot;: false, &quot;b&quot;: false, &quot;c&quot;: null, &quot;e&quot;: false, &quot;f&quot;: false, &quot;g&quot;: false, &quot;h&quot;: true, &quot;i&quot;: false }
8088</pre></div></div>
8089</li>
8090</ul>
8091<p>The function has an alias <tt>isarray</tt>.</p></div>
8092<div class="section">
8093<h3><a name="is_atomic_.28is_atom.29"></a>is_atomic (is_atom)</h3>
8094<ul>
8095
8096<li>
8097
8098<p>Syntax:</p>
8099
8100<div>
8101<div>
8102<pre class="source">is_atomic(expr)
8103</pre></div></div>
8104</li>
8105<li>
8106
8107<p>Checks whether the given expression is evaluated to be a value of a <a href="../datamodel.html#PrimitiveTypes">primitive</a> type.</p>
8108</li>
8109<li>Arguments:
8110<ul>
8111
8112<li><tt>expr</tt> : an expression (any type is allowed).</li>
8113</ul>
8114</li>
8115<li>Return Value:
8116<ul>
8117
8118<li>a <tt>boolean</tt> on whether the argument is a primitive type or not,</li>
8119<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
8120<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
8121</ul>
8122</li>
8123<li>
8124
8125<p>Example:</p>
8126
8127<div>
8128<div>
8129<pre class="source">{
8130 &quot;a&quot;: is_atomic(true),
8131 &quot;b&quot;: is_atomic(false),
8132 &quot;c&quot;: isatomic(null),
8133 &quot;d&quot;: isatomic(missing),
8134 &quot;e&quot;: isatomic(&quot;d&quot;),
8135 &quot;f&quot;: isatom(4.0),
8136 &quot;g&quot;: isatom(5),
8137 &quot;h&quot;: isatom([&quot;1&quot;, 2]),
8138 &quot;i&quot;: isatom({&quot;a&quot;:1})
8139};
8140</pre></div></div>
8141</li>
8142<li>
8143
8144<p>The expected result is:</p>
8145
8146<div>
8147<div>
8148<pre class="source">{ &quot;a&quot;: true, &quot;b&quot;: true, &quot;c&quot;: null, &quot;e&quot;: true, &quot;f&quot;: true, &quot;g&quot;: true, &quot;h&quot;: false, &quot;i&quot;: false }
8149</pre></div></div>
8150</li>
8151</ul>
8152<p>The function has three aliases: <tt>isatomic</tt>, <tt>is_atom</tt>, and <tt>isatom</tt>.</p></div>
8153<div class="section">
8154<h3><a name="is_boolean_.28is_bool.29"></a>is_boolean (is_bool)</h3>
8155<ul>
8156
8157<li>
8158
8159<p>Syntax:</p>
8160
8161<div>
8162<div>
8163<pre class="source">is_boolean(expr)
8164</pre></div></div>
8165</li>
8166<li>
8167
8168<p>Checks whether the given expression is evaluated to be a <tt>boolean</tt> value.</p>
8169</li>
8170<li>Arguments:
8171<ul>
8172
8173<li><tt>expr</tt> : an expression (any type is allowed).</li>
8174</ul>
8175</li>
8176<li>Return Value:
8177<ul>
8178
8179<li>a <tt>boolean</tt> on whether the argument is a <tt>boolean</tt> value or not,</li>
8180<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
8181<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
8182</ul>
8183</li>
8184<li>
8185
8186<p>Example:</p>
8187
8188<div>
8189<div>
8190<pre class="source">{
8191 &quot;a&quot;: isboolean(true),
8192 &quot;b&quot;: isboolean(false),
8193 &quot;c&quot;: is_boolean(null),
8194 &quot;d&quot;: is_boolean(missing),
8195 &quot;e&quot;: isbool(&quot;d&quot;),
8196 &quot;f&quot;: isbool(4.0),
8197 &quot;g&quot;: isbool(5),
8198 &quot;h&quot;: isbool([&quot;1&quot;, 2]),
8199 &quot;i&quot;: isbool({&quot;a&quot;:1})
8200};
8201</pre></div></div>
8202</li>
8203<li>
8204
8205<p>The expected result is:</p>
8206
8207<div>
8208<div>
8209<pre class="source">{ &quot;a&quot;: true, &quot;b&quot;: true, &quot;c&quot;: null, &quot;e&quot;: false, &quot;f&quot;: false, &quot;g&quot;: false, &quot;h&quot;: false, &quot;i&quot;: false }
8210</pre></div></div>
8211</li>
8212</ul>
8213<p>The function has three aliases: <tt>isboolean</tt>, <tt>is_bool</tt>, and <tt>isbool</tt>.</p></div>
8214<div class="section">
8215<h3><a name="is_number_.28is_num.29"></a>is_number (is_num)</h3>
8216<ul>
8217
8218<li>
8219
8220<p>Syntax:</p>
8221
8222<div>
8223<div>
8224<pre class="source">is_number(expr)
8225</pre></div></div>
8226</li>
8227<li>
8228
8229<p>Checks whether the given expression is evaluated to be a numeric value.</p>
8230</li>
8231<li>Arguments:
8232<ul>
8233
8234<li><tt>expr</tt> : an expression (any type is allowed).</li>
8235</ul>
8236</li>
8237<li>Return Value:
8238<ul>
8239
8240<li>a <tt>boolean</tt> on whether the argument is a <tt>smallint</tt>/<tt>tinyint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value or not,</li>
8241<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
8242<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
8243</ul>
8244</li>
8245<li>
8246
8247<p>Example:</p>
8248
8249<div>
8250<div>
8251<pre class="source">{
8252 &quot;a&quot;: is_number(true),
8253 &quot;b&quot;: is_number(false),
8254 &quot;c&quot;: isnumber(null),
8255 &quot;d&quot;: isnumber(missing),
8256 &quot;e&quot;: isnumber(&quot;d&quot;),
8257 &quot;f&quot;: isnum(4.0),
8258 &quot;g&quot;: isnum(5),
8259 &quot;h&quot;: isnum([&quot;1&quot;, 2]),
8260 &quot;i&quot;: isnum({&quot;a&quot;:1})
8261};
8262</pre></div></div>
8263</li>
8264<li>
8265
8266<p>The expected result is:</p>
8267
8268<div>
8269<div>
8270<pre class="source">{ &quot;a&quot;: false, &quot;b&quot;: false, &quot;c&quot;: null, &quot;e&quot;: false, &quot;f&quot;: true, &quot;g&quot;: true, &quot;h&quot;: false, &quot;i&quot;: false }
8271</pre></div></div>
8272</li>
8273</ul>
8274<p>The function has three aliases: <tt>isnumber</tt>, <tt>is_num</tt>, and <tt>isnum</tt>.</p></div>
8275<div class="section">
8276<h3><a name="is_object_.28is_obj.29"></a>is_object (is_obj)</h3>
8277<ul>
8278
8279<li>
8280
8281<p>Syntax:</p>
8282
8283<div>
8284<div>
8285<pre class="source">is_object(expr)
8286</pre></div></div>
8287</li>
8288<li>
8289
8290<p>Checks whether the given expression is evaluated to be a <tt>object</tt> value.</p>
8291</li>
8292<li>Arguments:
8293<ul>
8294
8295<li><tt>expr</tt> : an expression (any type is allowed).</li>
8296</ul>
8297</li>
8298<li>Return Value:
8299<ul>
8300
8301<li>a <tt>boolean</tt> on whether the argument is a <tt>object</tt> value or not,</li>
8302<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
8303<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
8304</ul>
8305</li>
8306<li>
8307
8308<p>Example:</p>
8309
8310<div>
8311<div>
8312<pre class="source">{
8313 &quot;a&quot;: is_object(true),
8314 &quot;b&quot;: is_object(false),
8315 &quot;c&quot;: isobject(null),
8316 &quot;d&quot;: isobject(missing),
8317 &quot;e&quot;: isobj(&quot;d&quot;),
8318 &quot;f&quot;: isobj(4.0),
8319 &quot;g&quot;: isobj(5),
8320 &quot;h&quot;: isobj([&quot;1&quot;, 2]),
8321 &quot;i&quot;: isobj({&quot;a&quot;:1})
8322};
8323</pre></div></div>
8324</li>
8325<li>
8326
8327<p>The expected result is:</p>
8328<p>{ &#x201c;a&#x201d;: false, &#x201c;b&#x201d;: false, &#x201c;c&#x201d;: null, &#x201c;e&#x201d;: false, &#x201c;f&#x201d;: false, &#x201c;g&#x201d;: false, &#x201c;h&#x201d;: false, &#x201c;i&#x201d;: true }</p>
8329</li>
8330</ul>
8331<p>The function has three aliases: <tt>isobject</tt>, <tt>is_obj</tt>, and <tt>isobj</tt>.</p></div>
8332<div class="section">
8333<h3><a name="is_string_.28is_str.29"></a>is_string (is_str)</h3>
8334<ul>
8335
8336<li>
8337
8338<p>Syntax:</p>
8339
8340<div>
8341<div>
8342<pre class="source">is_string(expr)
8343</pre></div></div>
8344</li>
8345<li>
8346
8347<p>Checks whether the given expression is evaluated to be a <tt>string</tt> value.</p>
8348</li>
8349<li>Arguments:
8350<ul>
8351
8352<li><tt>expr</tt> : an expression (any type is allowed).</li>
8353</ul>
8354</li>
8355<li>Return Value:
8356<ul>
8357
8358<li>a <tt>boolean</tt> on whether the argument is a <tt>string</tt> value or not,</li>
8359<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
8360<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
8361</ul>
8362</li>
8363<li>
8364
8365<p>Example:</p>
8366
8367<div>
8368<div>
8369<pre class="source">{
8370 &quot;a&quot;: is_string(true),
8371 &quot;b&quot;: isstring(false),
8372 &quot;c&quot;: isstring(null),
8373 &quot;d&quot;: isstr(missing),
8374 &quot;e&quot;: isstr(&quot;d&quot;),
8375 &quot;f&quot;: isstr(4.0),
8376 &quot;g&quot;: isstr(5),
8377 &quot;h&quot;: isstr([&quot;1&quot;, 2]),
8378 &quot;i&quot;: isstr({&quot;a&quot;:1})
8379};
8380</pre></div></div>
8381</li>
8382<li>
8383
8384<p>The expected result is:</p>
8385
8386<div>
8387<div>
8388<pre class="source">{ &quot;a&quot;: false, &quot;b&quot;: false, &quot;c&quot;: null, &quot;e&quot;: true, &quot;f&quot;: false, &quot;g&quot;: false, &quot;h&quot;: false, &quot;i&quot;: false }
8389</pre></div></div>
8390</li>
8391</ul>
8392<p>The function has three aliases: <tt>isstring</tt>, <tt>is_str</tt>, and <tt>isstr</tt>.</p></div>
8393<div class="section">
8394<h3><a name="is_null"></a>is_null</h3>
8395<ul>
8396
8397<li>
8398
8399<p>Syntax:</p>
8400
8401<div>
8402<div>
8403<pre class="source">is_null(expr)
8404</pre></div></div>
8405</li>
8406<li>
8407
8408<p>Checks whether the given expression is evaluated to be a <tt>null</tt> value.</p>
8409</li>
8410<li>Arguments:
8411<ul>
8412
8413<li><tt>expr</tt> : an expression (any type is allowed).</li>
8414</ul>
8415</li>
8416<li>Return Value:
8417<ul>
8418
8419<li>a <tt>boolean</tt> on whether the variable is a <tt>null</tt> or not,</li>
8420<li>a <tt>missing</tt> if the input is <tt>missing</tt>.</li>
8421</ul>
8422</li>
8423<li>
8424
8425<p>Example:</p>
8426
8427<div>
8428<div>
8429<pre class="source">{ &quot;v1&quot;: is_null(null), &quot;v2&quot;: is_null(1), &quot;v3&quot;: is_null(missing) };
8430</pre></div></div>
8431</li>
8432<li>
8433
8434<p>The expected result is:</p>
8435
8436<div>
8437<div>
8438<pre class="source">{ &quot;v1&quot;: true, &quot;v2&quot;: false }
8439</pre></div></div>
8440</li>
8441</ul>
8442<p>The function has an alias <tt>isnull</tt>.</p></div>
8443<div class="section">
8444<h3><a name="is_missing"></a>is_missing</h3>
8445<ul>
8446
8447<li>
8448
8449<p>Syntax:</p>
8450
8451<div>
8452<div>
8453<pre class="source">is_missing(expr)
8454</pre></div></div>
8455</li>
8456<li>
8457
8458<p>Checks whether the given expression is evaluated to be a <tt>missing</tt> value.</p>
8459</li>
8460<li>Arguments:
8461<ul>
8462
8463<li><tt>expr</tt> : an expression (any type is allowed).</li>
8464</ul>
8465</li>
8466<li>Return Value:
8467<ul>
8468
8469<li>a <tt>boolean</tt> on whether the variable is a <tt>missing</tt> or not.</li>
8470</ul>
8471</li>
8472<li>
8473
8474<p>Example:</p>
8475
8476<div>
8477<div>
8478<pre class="source">{ &quot;v1&quot;: is_missing(null), &quot;v2&quot;: is_missing(1), &quot;v3&quot;: is_missing(missing) };
8479</pre></div></div>
8480</li>
8481<li>
8482
8483<p>The expected result is:</p>
8484
8485<div>
8486<div>
8487<pre class="source">{ &quot;v1&quot;: false, &quot;v2&quot;: false, &quot;v3&quot;: true }
8488</pre></div></div>
8489</li>
8490</ul>
8491<p>The function has an alias <tt>ismissing</tt>.</p></div>
8492<div class="section">
8493<h3><a name="is_unknown"></a>is_unknown</h3>
8494<ul>
8495
8496<li>
8497
8498<p>Syntax:</p>
8499
8500<div>
8501<div>
8502<pre class="source">is_unknown(expr)
8503</pre></div></div>
8504</li>
8505<li>
8506
8507<p>Checks whether the given variable is a <tt>null</tt> value or a <tt>missing</tt> value.</p>
8508</li>
8509<li>Arguments:
8510<ul>
8511
8512<li><tt>expr</tt> : an expression (any type is allowed).</li>
8513</ul>
8514</li>
8515<li>Return Value:
8516<ul>
8517
8518<li>a <tt>boolean</tt> on whether the variable is a <tt>null</tt>/``missing<tt>value (</tt>true<tt>) or not (</tt>false`).</li>
8519</ul>
8520</li>
8521<li>
8522
8523<p>Example:</p>
8524
8525<div>
8526<div>
8527<pre class="source">{ &quot;v1&quot;: is_unknown(null), &quot;v2&quot;: is_unknown(1), &quot;v3&quot;: is_unknown(missing) };
8528</pre></div></div>
8529</li>
8530<li>
8531
8532<p>The expected result is:</p>
8533
8534<div>
8535<div>
8536<pre class="source">{ &quot;v1&quot;: true, &quot;v2&quot;: false, &quot;v3&quot;: true }
8537</pre></div></div>
8538</li>
8539</ul>
8540<p>The function has an alias <tt>isunknown</tt>.</p></div>
8541<div class="section">
8542<h3><a name="to_array"></a>to_array</h3>
8543<ul>
8544
8545<li>
8546
8547<p>Syntax:</p>
8548
8549<div>
8550<div>
8551<pre class="source">to_array(expr)
8552</pre></div></div>
8553</li>
8554<li>
8555
8556<p>Converts input value to an <tt>array</tt> value</p>
8557</li>
8558<li>Arguments:
8559<ul>
8560
8561<li><tt>expr</tt> : an expression</li>
8562</ul>
8563</li>
8564<li>Return Value:
8565<ul>
8566
8567<li>if the argument is <tt>missing</tt> then <tt>missing</tt> is returned</li>
8568<li>if the argument is <tt>null</tt> then <tt>null</tt> is returned</li>
8569<li>if the argument is of <tt>array</tt> type then it is returned as is</li>
8570<li>if the argument is of <tt>multiset</tt> type then it is returned as an <tt>array</tt> with elements in an undefined order</li>
8571<li>otherwise an <tt>array</tt> containing the input expression as its single item is returned</li>
8572</ul>
8573</li>
8574<li>
8575
8576<p>Example:</p>
8577
8578<div>
8579<div>
8580<pre class="source">{
8581 &quot;v1&quot;: to_array(&quot;asterix&quot;),
8582 &quot;v2&quot;: to_array([&quot;asterix&quot;]),
8583};
8584</pre></div></div>
8585</li>
8586<li>
8587
8588<p>The expected result is:</p>
8589
8590<div>
8591<div>
8592<pre class="source">{ &quot;v1&quot;: [&quot;asterix&quot;], &quot;v2&quot;: [&quot;asterix&quot;] }
8593</pre></div></div>
8594</li>
8595</ul>
8596<p>The function has an alias <tt>toarray</tt>.</p></div>
8597<div class="section">
8598<h3><a name="to_atomic_.28to_atom.29"></a>to_atomic (to_atom)</h3>
8599<ul>
8600
8601<li>
8602
8603<p>Syntax:</p>
8604
8605<div>
8606<div>
8607<pre class="source">to_atomic(expr)
8608</pre></div></div>
8609</li>
8610<li>
8611
8612<p>Converts input value to a <a href="../datamodel.html#PrimitiveTypes">primitive</a> value</p>
8613</li>
8614<li>Arguments:
8615<ul>
8616
8617<li><tt>expr</tt> : an expression</li>
8618</ul>
8619</li>
8620<li>Return Value:
8621<ul>
8622
8623<li>if the argument is <tt>missing</tt> then <tt>missing</tt> is returned</li>
8624<li>if the argument is <tt>null</tt> then <tt>null</tt> is returned</li>
8625<li>if the argument is of primitive type then it is returned as is</li>
8626<li>if the argument is of <tt>array</tt> or <tt>multiset</tt> type and has only one element then the result of invoking to_atomic() on that element is returned</li>
8627<li>if the argument is of <tt>object</tt> type and has only one field then the result of invoking to_atomic() on the value of that field is returned</li>
8628<li>otherwise <tt>null</tt> is returned</li>
8629</ul>
8630</li>
8631<li>
8632
8633<p>Example:</p>
8634
8635<div>
8636<div>
8637<pre class="source">{
8638 &quot;v1&quot;: to_atomic(&quot;asterix&quot;),
8639 &quot;v2&quot;: to_atomic([&quot;asterix&quot;]),
8640 &quot;v3&quot;: to_atomic([0, 1]),
8641 &quot;v4&quot;: to_atomic({&quot;value&quot;: &quot;asterix&quot;}),
8642 &quot;v5&quot;: to_number({&quot;x&quot;: 1, &quot;y&quot;: 2})
8643};
8644</pre></div></div>
8645</li>
8646<li>
8647
8648<p>The expected result is:</p>
8649
8650<div>
8651<div>
8652<pre class="source">{ &quot;v1&quot;: &quot;asterix&quot;, &quot;v2&quot;: &quot;asterix&quot;, &quot;v3&quot;: null, &quot;v4&quot;: &quot;asterix&quot;, &quot;v5&quot;: null }
8653</pre></div></div>
8654</li>
8655</ul>
8656<p>The function has three aliases: <tt>toatomic</tt>, <tt>to_atom</tt>, and <tt>toatom</tt>.</p></div>
8657<div class="section">
8658<h3><a name="to_boolean_.28to_bool.29"></a>to_boolean (to_bool)</h3>
8659<ul>
8660
8661<li>
8662
8663<p>Syntax:</p>
8664
8665<div>
8666<div>
8667<pre class="source">to_boolean(expr)
8668</pre></div></div>
8669</li>
8670<li>
8671
8672<p>Converts input value to a <tt>boolean</tt> value</p>
8673</li>
8674<li>Arguments:
8675<ul>
8676
8677<li><tt>expr</tt> : an expression</li>
8678</ul>
8679</li>
8680<li>Return Value:
8681<ul>
8682
8683<li>if the argument is <tt>missing</tt> then <tt>missing</tt> is returned</li>
8684<li>if the argument is <tt>null</tt> then <tt>null</tt> is returned</li>
8685<li>if the argument is of <tt>boolean</tt> type then it is returned as is</li>
8686<li>if the argument is of numeric type then <tt>false</tt> is returned if it is <tt>0</tt> or <tt>NaN</tt>, otherwise <tt>true</tt></li>
8687<li>if the argument is of <tt>string</tt> type then <tt>false</tt> is returned if it&#x2019;s empty, otherwise <tt>true</tt></li>
8688<li>if the argument is of <tt>array</tt> or <tt>multiset</tt> type then <tt>false</tt> is returned if it&#x2019;s size is <tt>0</tt>, otherwise <tt>true</tt></li>
8689<li>if the argument is of <tt>object</tt> type then <tt>false</tt> is returned if it has no fields, otherwise <tt>true</tt></li>
8690<li>type error is raised for all other input types</li>
8691</ul>
8692</li>
8693<li>
8694
8695<p>Example:</p>
8696
8697<div>
8698<div>
8699<pre class="source">{
8700 &quot;v1&quot;: to_boolean(0),
8701 &quot;v2&quot;: to_boolean(1),
8702 &quot;v3&quot;: to_boolean(&quot;&quot;),
8703 &quot;v4&quot;: to_boolean(&quot;asterix&quot;)
8704};
8705</pre></div></div>
8706</li>
8707<li>
8708
8709<p>The expected result is:</p>
8710
8711<div>
8712<div>
8713<pre class="source">{ &quot;v1&quot;: false, &quot;v2&quot;: true, &quot;v3&quot;: false, &quot;v4&quot;: true }
8714</pre></div></div>
8715</li>
8716</ul>
8717<p>The function has three aliases: <tt>toboolean</tt>, <tt>to_bool</tt>, and <tt>tobool</tt>.</p></div>
8718<div class="section">
8719<h3><a name="to_bigint"></a>to_bigint</h3>
8720<ul>
8721
8722<li>
8723
8724<p>Syntax:</p>
8725
8726<div>
8727<div>
8728<pre class="source">to_bigint(expr)
8729</pre></div></div>
8730</li>
8731<li>
8732
8733<p>Converts input value to an integer value</p>
8734</li>
8735<li>Arguments:
8736<ul>
8737
8738<li><tt>expr</tt> : an expression</li>
8739</ul>
8740</li>
8741<li>Return Value:
8742<ul>
8743
8744<li>if the argument is <tt>missing</tt> then <tt>missing</tt> is returned</li>
8745<li>if the argument is <tt>null</tt> then <tt>null</tt> is returned</li>
8746<li>if the argument is of <tt>boolean</tt> type then <tt>1</tt> is returned if it is <tt>true</tt>, <tt>0</tt> if it is <tt>false</tt></li>
8747<li>if the argument is of numeric integer type then it is returned as the same value of <tt>bigint</tt> type</li>
8748<li>if the argument is of numeric <tt>float</tt>/<tt>double</tt> type then it is converted to <tt>bigint</tt> type</li>
8749<li>if the argument is of <tt>string</tt> type and can be parsed as integer then that integer value is returned, otherwise <tt>null</tt> is returned</li>
8750<li>if the argument is of <tt>array</tt>/<tt>multiset</tt>/<tt>object</tt> type then <tt>null</tt> is returned</li>
8751<li>type error is raised for all other input types</li>
8752</ul>
8753</li>
8754<li>
8755
8756<p>Example:</p>
8757
8758<div>
8759<div>
8760<pre class="source">{
8761 &quot;v1&quot;: to_bigint(false),
8762 &quot;v2&quot;: to_bigint(true),
8763 &quot;v3&quot;: to_bigint(10),
8764 &quot;v4&quot;: to_bigint(float(&quot;1e100&quot;)),
8765 &quot;v5&quot;: to_bigint(double(&quot;1e1000&quot;)),
8766 &quot;v6&quot;: to_bigint(&quot;20&quot;)
8767};
8768</pre></div></div>
8769</li>
8770<li>
8771
8772<p>The expected result is:</p>
8773
8774<div>
8775<div>
8776<pre class="source">{ &quot;v1&quot;: 0, &quot;v2&quot;: 1, &quot;v3&quot;: 10, &quot;v4&quot;: 9223372036854775807, &quot;v5&quot;: 9223372036854775807, &quot;v6&quot;: 20 }
8777</pre></div></div>
8778</li>
8779</ul>
8780<p>The function has an alias <tt>tobigint</tt>.</p></div>
8781<div class="section">
8782<h3><a name="to_double"></a>to_double</h3>
8783<ul>
8784
8785<li>
8786
8787<p>Syntax:</p>
8788
8789<div>
8790<div>
8791<pre class="source">to_double(expr)
8792</pre></div></div>
8793</li>
8794<li>
8795
8796<p>Converts input value to a <tt>double</tt> value</p>
8797</li>
8798<li>Arguments:
8799<ul>
8800
8801<li><tt>expr</tt> : an expression</li>
8802</ul>
8803</li>
8804<li>Return Value:
8805<ul>
8806
8807<li>if the argument is <tt>missing</tt> then <tt>missing</tt> is returned</li>
8808<li>if the argument is <tt>null</tt> then <tt>null</tt> is returned</li>
8809<li>if the argument is of <tt>boolean</tt> type then <tt>1.0</tt> is returned if it is <tt>true</tt>, <tt>0.0</tt> if it is <tt>false</tt></li>
8810<li>if the argument is of numeric type then it is returned as the value of <tt>double</tt> type</li>
8811<li>if the argument is of <tt>string</tt> type and can be parsed as <tt>double</tt> then that <tt>double</tt> value is returned, otherwise <tt>null</tt> is returned</li>
8812<li>if the argument is of <tt>array</tt>/<tt>multiset</tt>/<tt>object</tt> type then <tt>null</tt> is returned</li>
8813<li>type error is raised for all other input types</li>
8814</ul>
8815</li>
8816<li>
8817
8818<p>Example:</p>
8819
8820<div>
8821<div>
8822<pre class="source">{
8823 &quot;v1&quot;: to_double(false),
8824 &quot;v2&quot;: to_double(true),
8825 &quot;v3&quot;: to_double(10),
8826 &quot;v4&quot;: to_double(11.5),
8827 &quot;v5&quot;: to_double(&quot;12.5&quot;)
8828};
8829</pre></div></div>
8830</li>
8831<li>
8832
8833<p>The expected result is:</p>
8834
8835<div>
8836<div>
8837<pre class="source">{ &quot;v1&quot;: 0.0, &quot;v2&quot;: 1.0, &quot;v3&quot;: 10.0, &quot;v4&quot;: 11.5, &quot;v5&quot;: 12.5 }
8838</pre></div></div>
8839</li>
8840</ul>
8841<p>The function has an alias <tt>todouble</tt>.</p></div>
8842<div class="section">
8843<h3><a name="to_number_.28to_num.29"></a>to_number (to_num)</h3>
8844<ul>
8845
8846<li>
8847
8848<p>Syntax:</p>
8849
8850<div>
8851<div>
8852<pre class="source">to_number(expr)
8853</pre></div></div>
8854</li>
8855<li>
8856
8857<p>Converts input value to a numeric value</p>
8858</li>
8859<li>Arguments:
8860<ul>
8861
8862<li><tt>expr</tt> : an expression</li>
8863</ul>
8864</li>
8865<li>Return Value:
8866<ul>
8867
8868<li>if the argument is <tt>missing</tt> then <tt>missing</tt> is returned</li>
8869<li>if the argument is <tt>null</tt> then <tt>null</tt> is returned</li>
8870<li>if the argument is of numeric type then it is returned as is</li>
8871<li>if the argument is of <tt>boolean</tt> type then <tt>1</tt> is returned if it is <tt>true</tt>, <tt>0</tt> if it is <tt>false</tt></li>
8872<li>if the argument is of <tt>string</tt> type and can be parsed as <tt>bigint</tt> then that <tt>bigint</tt> value is returned, otherwise if it can be parsed as <tt>double</tt> then that <tt>double</tt> value is returned, otherwise <tt>null</tt> is returned</li>
8873<li>if the argument is of <tt>array</tt>/<tt>multiset</tt>/<tt>object</tt> type then <tt>null</tt> is returned</li>
8874<li>type error is raised for all other input types</li>
8875</ul>
8876</li>
8877<li>
8878
8879<p>Example:</p>
8880
8881<div>
8882<div>
8883<pre class="source">{
8884 &quot;v1&quot;: to_number(false),
8885 &quot;v2&quot;: to_number(true),
8886 &quot;v3&quot;: to_number(10),
8887 &quot;v4&quot;: to_number(11.5),
8888 &quot;v5&quot;: to_number(&quot;12.5&quot;)
8889};
8890</pre></div></div>
8891</li>
8892<li>
8893
8894<p>The expected result is:</p>
8895
8896<div>
8897<div>
8898<pre class="source">{ &quot;v1&quot;: 0, &quot;v2&quot;: 1, &quot;v3&quot;: 10, &quot;v4&quot;: 11.5, &quot;v5&quot;: 12.5 }
8899</pre></div></div>
8900</li>
8901</ul>
8902<p>The function has three aliases: <tt>tonumber</tt>, <tt>to_num</tt>, and <tt>tonum</tt>.</p></div>
8903<div class="section">
8904<h3><a name="to_object_.28to_obj.29"></a>to_object (to_obj)</h3>
8905<ul>
8906
8907<li>
8908
8909<p>Syntax:</p>
8910
8911<div>
8912<div>
8913<pre class="source">to_object(expr)
8914</pre></div></div>
8915</li>
8916<li>
8917
8918<p>Converts input value to an <tt>object</tt> value</p>
8919</li>
8920<li>Arguments:
8921<ul>
8922
8923<li><tt>expr</tt> : an expression</li>
8924</ul>
8925</li>
8926<li>Return Value:
8927<ul>
8928
8929<li>if the argument is <tt>missing</tt> then <tt>missing</tt> is returned</li>
8930<li>if the argument is <tt>null</tt> then <tt>null</tt> is returned</li>
8931<li>if the argument is of <tt>object</tt> type then it is returned as is</li>
8932<li>otherwise an empty <tt>object</tt> is returned</li>
8933</ul>
8934</li>
8935<li>
8936
8937<p>Example:</p>
8938
8939<div>
8940<div>
8941<pre class="source">{
8942 &quot;v1&quot;: to_object({&quot;value&quot;: &quot;asterix&quot;}),
8943 &quot;v2&quot;: to_object(&quot;asterix&quot;)
8944};
8945</pre></div></div>
8946</li>
8947<li>
8948
8949<p>The expected result is:</p>
8950
8951<div>
8952<div>
8953<pre class="source">{ &quot;v1&quot;: {&quot;value&quot;: &quot;asterix&quot;}, &quot;v2&quot;: {} }
8954</pre></div></div>
8955</li>
8956</ul>
8957<p>The function has three aliases: <tt>toobject</tt>, <tt>to_obj</tt>, and <tt>toobj</tt>.</p></div>
8958<div class="section">
8959<h3><a name="to_string_.28to_str.29"></a>to_string (to_str)</h3>
8960<ul>
8961
8962<li>
8963
8964<p>Syntax:</p>
8965
8966<div>
8967<div>
8968<pre class="source">to_string(expr)
8969</pre></div></div>
8970</li>
8971<li>
8972
8973<p>Converts input value to a string value</p>
8974</li>
8975<li>Arguments:
8976<ul>
8977
8978<li><tt>expr</tt> : an expression</li>
8979</ul>
8980</li>
8981<li>Return Value:
8982<ul>
8983
8984<li>if the argument is <tt>missing</tt> then <tt>missing</tt> is returned</li>
8985<li>if the argument is <tt>null</tt> then <tt>null</tt> is returned</li>
8986<li>if the argument is of <tt>boolean</tt> type then <tt>&quot;true&quot;</tt> is returned if it is <tt>true</tt>, <tt>&quot;false&quot;</tt> if it is <tt>false</tt></li>
8987<li>if the argument is of numeric type then its string representation is returned</li>
8988<li>if the argument is of <tt>string</tt> type then it is returned as is</li>
8989<li>if the argument is of <tt>array</tt>/<tt>multiset</tt>/<tt>object</tt> type then <tt>null</tt> is returned</li>
8990<li>type error is raised for all other input types</li>
8991</ul>
8992</li>
8993<li>
8994
8995<p>Example:</p>
8996
8997<div>
8998<div>
8999<pre class="source">{
9000 &quot;v1&quot;: to_string(false),
9001 &quot;v2&quot;: to_string(true),
9002 &quot;v3&quot;: to_string(10),
9003 &quot;v4&quot;: to_string(11.5),
9004 &quot;v5&quot;: to_string(&quot;asterix&quot;)
9005};
9006</pre></div></div>
9007</li>
9008<li>
9009
9010<p>The expected result is:</p>
9011
9012<div>
9013<div>
9014<pre class="source">{ &quot;v1&quot;: &quot;false&quot;, &quot;v2&quot;: &quot;true&quot;, &quot;v3&quot;: &quot;10&quot;, &quot;v4&quot;: &quot;11.5&quot;, &quot;v5&quot;: &quot;asterix&quot; }
9015</pre></div></div>
9016</li>
9017</ul>
9018<p>The function has three aliases: <tt>tostring</tt>, <tt>to_str</tt>, and <tt>tostr</tt>.</p><!--
9019 ! Licensed to the Apache Software Foundation (ASF) under one
9020 ! or more contributor license agreements. See the NOTICE file
9021 ! distributed with this work for additional information
9022 ! regarding copyright ownership. The ASF licenses this file
9023 ! to you under the Apache License, Version 2.0 (the
9024 ! "License"); you may not use this file except in compliance
9025 ! with the License. You may obtain a copy of the License at
9026 !
9027 ! http://www.apache.org/licenses/LICENSE-2.0
9028 !
9029 ! Unless required by applicable law or agreed to in writing,
9030 ! software distributed under the License is distributed on an
9031 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
9032 ! KIND, either express or implied. See the License for the
9033 ! specific language governing permissions and limitations
9034 ! under the License.
9035 !-->
9036</div></div>
9037<div class="section">
9038<h2><a name="Conditional_Functions"></a><a name="ConditionalFunctions" id="ConditionalFunctions">Conditional Functions</a></h2>
9039<div class="section">
9040<h3><a name="if_null_.28ifnull.29"></a>if_null (ifnull)</h3>
9041<ul>
9042
9043<li>
9044
9045<p>Syntax:</p>
9046
9047<div>
9048<div>
9049<pre class="source">if_null(expression1, expression2, ... expressionN)
9050</pre></div></div>
9051</li>
9052<li>
9053
9054<p>Finds first argument which value is not <tt>null</tt> and returns that value</p>
9055</li>
9056<li>Arguments:
9057<ul>
9058
9059<li><tt>expressionI</tt> : an expression (any type is allowed).</li>
9060</ul>
9061</li>
9062<li>Return Value:
9063<ul>
9064
9065<li>a <tt>null</tt> if all arguments evaluate to <tt>null</tt> or no arguments specified</li>
9066<li>a value of the first non-<tt>null</tt> argument otherwise</li>
9067</ul>
9068</li>
9069<li>
9070
9071<p>Example:</p>
9072
9073<div>
9074<div>
9075<pre class="source">{
9076 &quot;a&quot;: if_null(),
9077 &quot;b&quot;: if_null(null),
9078 &quot;c&quot;: if_null(null, &quot;asterixdb&quot;),
9079 &quot;d&quot;: is_missing(if_null(missing))
9080};
9081</pre></div></div>
9082</li>
9083<li>
9084
9085<p>The expected result is:</p>
9086
9087<div>
9088<div>
9089<pre class="source">{ &quot;a&quot;: null, &quot;b&quot;: null, &quot;c&quot;: &quot;asterixdb&quot;, &quot;d&quot;: true }
9090</pre></div></div>
9091</li>
9092</ul>
9093<p>The function has an alias <tt>ifnull</tt>.</p></div>
9094<div class="section">
9095<h3><a name="if_missing_.28ifmissing.29"></a>if_missing (ifmissing)</h3>
9096<ul>
9097
9098<li>
9099
9100<p>Syntax:</p>
9101
9102<div>
9103<div>
9104<pre class="source">if_missing(expression1, expression2, ... expressionN)
9105</pre></div></div>
9106</li>
9107<li>
9108
9109<p>Finds first argument which value is not <tt>missing</tt> and returns that value</p>
9110</li>
9111<li>Arguments:
9112<ul>
9113
9114<li><tt>expressionI</tt> : an expression (any type is allowed).</li>
9115</ul>
9116</li>
9117<li>Return Value:
9118<ul>
9119
9120<li>a <tt>null</tt> if all arguments evaluate to <tt>missing</tt> or no arguments specified</li>
9121<li>a value of the first non-<tt>missing</tt> argument otherwise</li>
9122</ul>
9123</li>
9124<li>
9125
9126<p>Example:</p>
9127
9128<div>
9129<div>
9130<pre class="source">{
9131 &quot;a&quot;: if_missing(),
9132 &quot;b&quot;: if_missing(missing),
9133 &quot;c&quot;: if_missing(missing, &quot;asterixdb&quot;),
9134 &quot;d&quot;: if_missing(null, &quot;asterixdb&quot;)
9135};
9136</pre></div></div>
9137</li>
9138<li>
9139
9140<p>The expected result is:</p>
9141
9142<div>
9143<div>
9144<pre class="source">{ &quot;a&quot;: null, &quot;b&quot;: null, &quot;c&quot;: &quot;asterixdb&quot;, &quot;d&quot;: null }
9145</pre></div></div>
9146</li>
9147</ul>
9148<p>The function has an alias <tt>ifmissing</tt>.</p></div>
9149<div class="section">
9150<h3><a name="if_missing_or_null_.28ifmissingornull.29"></a>if_missing_or_null (ifmissingornull)</h3>
9151<ul>
9152
9153<li>
9154
9155<p>Syntax:</p>
9156
9157<div>
9158<div>
9159<pre class="source">if_missing_or_null(expression1, expression2, ... expressionN)
9160</pre></div></div>
9161</li>
9162<li>
9163
9164<p>Finds first argument which value is not <tt>null</tt> or <tt>missing</tt> and returns that value</p>
9165</li>
9166<li>Arguments:
9167<ul>
9168
9169<li><tt>expressionI</tt> : an expression (any type is allowed).</li>
9170</ul>
9171</li>
9172<li>Return Value:
9173<ul>
9174
9175<li>a <tt>null</tt> if all arguments evaluate to either <tt>null</tt> or <tt>missing</tt>, or no arguments specified</li>
9176<li>a value of the first non-<tt>null</tt>, non-<tt>missing</tt> argument otherwise</li>
9177</ul>
9178</li>
9179<li>
9180
9181<p>Example:</p>
9182
9183<div>
9184<div>
9185<pre class="source">{
9186 &quot;a&quot;: if_missing_or_null(),
9187 &quot;b&quot;: if_missing_or_null(null, missing),
9188 &quot;c&quot;: if_missing_or_null(null, missing, &quot;asterixdb&quot;)
9189};
9190</pre></div></div>
9191</li>
9192<li>
9193
9194<p>The expected result is:</p>
9195
9196<div>
9197<div>
9198<pre class="source">{ &quot;a&quot;: null, &quot;b&quot;: null, &quot;c&quot;: &quot;asterixdb&quot; }
9199</pre></div></div>
9200</li>
9201</ul>
9202<p>The function has an alias <tt>ifmissingornull</tt>.</p></div>
9203<div class="section">
9204<h3><a name="if_inf_.28ifinf.29"></a>if_inf (ifinf)</h3>
9205<ul>
9206
9207<li>
9208
9209<p>Syntax:</p>
9210
9211<div>
9212<div>
9213<pre class="source">if_inf(expression1, expression2, ... expressionN)
9214</pre></div></div>
9215</li>
9216<li>
9217
9218<p>Finds first argument which is a non-infinite (<tt>INF</tt> or<tt>-INF</tt>) number</p>
9219</li>
9220<li>Arguments:
9221<ul>
9222
9223<li><tt>expressionI</tt> : an expression (any type is allowed).</li>
9224</ul>
9225</li>
9226<li>Return Value:
9227<ul>
9228
9229<li>a <tt>missing</tt> if <tt>missing</tt> argument was encountered before the first non-infinite number argument</li>
9230<li>a <tt>null</tt> if <tt>null</tt> argument or any other non-number argument was encountered before the first non-infinite number argument</li>
9231<li>the first non-infinite number argument otherwise</li>
9232</ul>
9233</li>
9234<li>
9235
9236<p>Example:</p>
9237
9238<div>
9239<div>
9240<pre class="source">{
9241 &quot;a&quot;: is_null(if_inf(null)),
9242 &quot;b&quot;: is_missing(if_inf(missing)),
9243 &quot;c&quot;: is_null(if_inf(double(&quot;INF&quot;))),
9244 &quot;d&quot;: if_inf(1, null, missing) ],
9245 &quot;e&quot;: is_null(if_inf(null, missing, 1)) ],
9246 &quot;f&quot;: is_missing(if_inf(missing, null, 1)) ],
9247 &quot;g&quot;: if_inf(float(&quot;INF&quot;), 1) ],
9248 &quot;h&quot;: to_string(if_inf(float(&quot;INF&quot;), double(&quot;NaN&quot;), 1)) ]
9249};
9250</pre></div></div>
9251</li>
9252<li>
9253
9254<p>The expected result is:</p>
9255
9256<div>
9257<div>
9258<pre class="source">{ &quot;a&quot;: true, &quot;b&quot;: true, &quot;c&quot;: true, &quot;d&quot;: 1, &quot;e&quot;: true, &quot;f&quot;: true, &quot;g&quot;: 1, &quot;h&quot;: &quot;NaN&quot; }
9259</pre></div></div>
9260</li>
9261</ul>
9262<p>The function has an alias <tt>ifinf</tt>.</p></div>
9263<div class="section">
9264<h3><a name="if_nan_.28ifnan.29"></a>if_nan (ifnan)</h3>
9265<ul>
9266
9267<li>
9268
9269<p>Syntax:</p>
9270
9271<div>
9272<div>
9273<pre class="source">if_nan(expression1, expression2, ... expressionN)
9274</pre></div></div>
9275</li>
9276<li>
9277
9278<p>Finds first argument which is a non-<tt>NaN</tt> number</p>
9279</li>
9280<li>Arguments:
9281<ul>
9282
9283<li><tt>expressionI</tt> : an expression (any type is allowed).</li>
9284</ul>
9285</li>
9286<li>Return Value:
9287<ul>
9288
9289<li>a <tt>missing</tt> if <tt>missing</tt> argument was encountered before the first non-<tt>NaN</tt> number argument</li>
9290<li>a <tt>null</tt> if <tt>null</tt> argument or any other non-number argument was encountered before the first non-<tt>NaN</tt> number argument</li>
9291<li>the first non-<tt>NaN</tt> number argument otherwise</li>
9292</ul>
9293</li>
9294<li>
9295
9296<p>Example:</p>
9297
9298<div>
9299<div>
9300<pre class="source">{
9301 &quot;a&quot;: is_null(if_nan(null)),
9302 &quot;b&quot;: is_missing(if_nan(missing)),
9303 &quot;c&quot;: is_null(if_nan(double(&quot;NaN&quot;))),
9304 &quot;d&quot;: if_nan(1, null, missing) ],
9305 &quot;e&quot;: is_null(if_nan(null, missing, 1)) ],
9306 &quot;f&quot;: is_missing(if_nan(missing, null, 1)) ],
9307 &quot;g&quot;: if_nan(float(&quot;NaN&quot;), 1) ],
9308 &quot;h&quot;: to_string(if_nan(float(&quot;NaN&quot;), double(&quot;INF&quot;), 1)) ]
9309};
9310</pre></div></div>
9311</li>
9312<li>
9313
9314<p>The expected result is:</p>
9315
9316<div>
9317<div>
9318<pre class="source">{ &quot;a&quot;: true, &quot;b&quot;: true, &quot;c&quot;: true, &quot;d&quot;: 1, &quot;e&quot;: true, &quot;f&quot;: true, &quot;g&quot;: 1, &quot;h&quot;: &quot;INF&quot; }
9319</pre></div></div>
9320</li>
9321</ul>
9322<p>The function has an alias <tt>ifnan</tt>.</p></div>
9323<div class="section">
9324<h3><a name="if_nan_or_inf_.28ifnanorinf.29"></a>if_nan_or_inf (ifnanorinf)</h3>
9325<ul>
9326
9327<li>
9328
9329<p>Syntax:</p>
9330
9331<div>
9332<div>
9333<pre class="source">if_nan_or_inf(expression1, expression2, ... expressionN)
9334</pre></div></div>
9335</li>
9336<li>
9337
9338<p>Finds first argument which is a non-infinite (<tt>INF</tt> or<tt>-INF</tt>) and non-<tt>NaN</tt> number</p>
9339</li>
9340<li>Arguments:
9341<ul>
9342
9343<li><tt>expressionI</tt> : an expression (any type is allowed).</li>
9344</ul>
9345</li>
9346<li>Return Value:
9347<ul>
9348
9349<li>a <tt>missing</tt> if <tt>missing</tt> argument was encountered before the first non-infinite and non-<tt>NaN</tt> number argument</li>
9350<li>a <tt>null</tt> if <tt>null</tt> argument or any other non-number argument was encountered before the first non-infinite and non-<tt>NaN</tt> number argument</li>
9351<li>the first non-infinite and non-<tt>NaN</tt> number argument otherwise</li>
9352</ul>
9353</li>
9354<li>
9355
9356<p>Example:</p>
9357
9358<div>
9359<div>
9360<pre class="source">{
9361 &quot;a&quot;: is_null(if_nan_or_inf(null)),
9362 &quot;b&quot;: is_missing(if_nan_or_inf(missing)),
9363 &quot;c&quot;: is_null(if_nan_or_inf(double(&quot;NaN&quot;), double(&quot;INF&quot;))),
9364 &quot;d&quot;: if_nan_or_inf(1, null, missing) ],
9365 &quot;e&quot;: is_null(if_nan_or_inf(null, missing, 1)) ],
9366 &quot;f&quot;: is_missing(if_nan_or_inf(missing, null, 1)) ],
9367 &quot;g&quot;: if_nan_or_inf(float(&quot;NaN&quot;), float(&quot;INF&quot;), 1) ],
9368};
9369</pre></div></div>
9370</li>
9371<li>
9372
9373<p>The expected result is:</p>
9374
9375<div>
9376<div>
9377<pre class="source">{ &quot;a&quot;: true, &quot;b&quot;: true, &quot;c&quot;: true, &quot;d&quot;: 1, &quot;e&quot;: true, &quot;f&quot;: true, &quot;g&quot;: 1 }
9378</pre></div></div>
9379</li>
9380</ul>
9381<p>The function has an alias <tt>ifnanorinf</tt>.</p></div>
9382<div class="section">
9383<h3><a name="null_if_.28nullif.29"></a>null_if (nullif)</h3>
9384<ul>
9385
9386<li>
9387
9388<p>Syntax:</p>
9389
9390<div>
9391<div>
9392<pre class="source">null_if(expression1, expression2)
9393</pre></div></div>
9394</li>
9395<li>
9396
9397<p>Compares two arguments and returns <tt>null</tt> if they are equal, otherwise returns the first argument.</p>
9398</li>
9399<li>Arguments:
9400<ul>
9401
9402<li><tt>expressionI</tt> : an expression (any type is allowed).</li>
9403</ul>
9404</li>
9405<li>Return Value:
9406<ul>
9407
9408<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
9409<li><tt>null</tt> if
9410<ul>
9411
9412<li>any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value, or</li>
9413<li><tt>argument1</tt> = <tt>argument2</tt></li>
9414</ul>
9415</li>
9416<li>a value of the first argument otherwise</li>
9417</ul>
9418</li>
9419<li>
9420
9421<p>Example:</p>
9422
9423<div>
9424<div>
9425<pre class="source">{
9426 &quot;a&quot;: null_if(&quot;asterixdb&quot;, &quot;asterixdb&quot;),
9427 &quot;b&quot;: null_if(1, 2)
9428};
9429</pre></div></div>
9430</li>
9431<li>
9432
9433<p>The expected result is:</p>
9434
9435<div>
9436<div>
9437<pre class="source">{ &quot;a&quot;: null, &quot;b&quot;: 1 }
9438</pre></div></div>
9439</li>
9440</ul>
9441<p>The function has an alias <tt>nullif</tt>.</p></div>
9442<div class="section">
9443<h3><a name="missing_if_.28missingif.29"></a>missing_if (missingif)</h3>
9444<ul>
9445
9446<li>
9447
9448<p>Syntax:</p>
9449
9450<div>
9451<div>
9452<pre class="source">missing_if(expression1, expression2)
9453</pre></div></div>
9454</li>
9455<li>
9456
9457<p>Compares two arguments and returns <tt>missing</tt> if they are equal, otherwise returns the first argument.</p>
9458</li>
9459<li>Arguments:
9460<ul>
9461
9462<li><tt>expressionI</tt> : an expression (any type is allowed).</li>
9463</ul>
9464</li>
9465<li>Return Value:
9466<ul>
9467
9468<li><tt>missing</tt> if
9469<ul>
9470
9471<li>any argument is a <tt>missing</tt> value, or</li>
9472<li>no argument is a <tt>null</tt> value and <tt>argument1</tt> = <tt>argument2</tt></li>
9473</ul>
9474</li>
9475<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value</li>
9476<li>a value of the first argument otherwise</li>
9477</ul>
9478</li>
9479<li>
9480
9481<p>Example:</p>
9482
9483<div>
9484<div>
9485<pre class="source">{
9486 &quot;a&quot;: missing_if(&quot;asterixdb&quot;, &quot;asterixdb&quot;)
9487 &quot;b&quot;: missing_if(1, 2),
9488};
9489</pre></div></div>
9490</li>
9491<li>
9492
9493<p>The expected result is:</p>
9494
9495<div>
9496<div>
9497<pre class="source">{ &quot;b&quot;: 1 }
9498</pre></div></div>
9499</li>
9500</ul>
9501<p>The function has an alias <tt>missingif</tt>.</p></div>
9502<div class="section">
9503<h3><a name="nan_if_.28nanif.29"></a>nan_if (nanif)</h3>
9504<ul>
9505
9506<li>
9507
9508<p>Syntax:</p>
9509
9510<div>
9511<div>
9512<pre class="source">nan_if(expression1, expression2)
9513</pre></div></div>
9514</li>
9515<li>
9516
9517<p>Compares two arguments and returns <tt>NaN</tt> value if they are equal, otherwise returns the first argument.</p>
9518</li>
9519<li>Arguments:
9520<ul>
9521
9522<li><tt>expressionI</tt> : an expression (any type is allowed).</li>
9523</ul>
9524</li>
9525<li>Return Value:
9526<ul>
9527
9528<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
9529<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value</li>
9530<li><tt>NaN</tt> value of type <tt>double</tt> if <tt>argument1</tt> = <tt>argument2</tt></li>
9531<li>a value of the first argument otherwise</li>
9532</ul>
9533</li>
9534<li>
9535
9536<p>Example:</p>
9537
9538<div>
9539<div>
9540<pre class="source">{
9541 &quot;a&quot;: to_string(nan_if(&quot;asterixdb&quot;, &quot;asterixdb&quot;)),
9542 &quot;b&quot;: nan_if(1, 2)
9543};
9544</pre></div></div>
9545</li>
9546<li>
9547
9548<p>The expected result is:</p>
9549
9550<div>
9551<div>
9552<pre class="source">{ &quot;a&quot;: &quot;NaN&quot;, &quot;b&quot;: 1 }
9553</pre></div></div>
9554</li>
9555</ul>
9556<p>The function has an alias <tt>nanif</tt>.</p></div>
9557<div class="section">
9558<h3><a name="posinf_if_.28posinfif.29"></a>posinf_if (posinfif)</h3>
9559<ul>
9560
9561<li>
9562
9563<p>Syntax:</p>
9564
9565<div>
9566<div>
9567<pre class="source">posinf_if(expression1, expression2)
9568</pre></div></div>
9569</li>
9570<li>
9571
9572<p>Compares two arguments and returns <tt>+INF</tt> value if they are equal, otherwise returns the first argument.</p>
9573</li>
9574<li>Arguments:
9575<ul>
9576
9577<li><tt>expressionI</tt> : an expression (any type is allowed).</li>
9578</ul>
9579</li>
9580<li>Return Value:
9581<ul>
9582
9583<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
9584<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value</li>
9585<li><tt>+INF</tt> value of type <tt>double</tt> if <tt>argument1</tt> = <tt>argument2</tt></li>
9586<li>a value of the first argument otherwise</li>
9587</ul>
9588</li>
9589<li>
9590
9591<p>Example:</p>
9592
9593<div>
9594<div>
9595<pre class="source">{
9596 &quot;a&quot;: to_string(posinf_if(&quot;asterixdb&quot;, &quot;asterixdb&quot;)),
9597 &quot;b&quot;: posinf_if(1, 2)
9598};
9599</pre></div></div>
9600</li>
9601<li>
9602
9603<p>The expected result is:</p>
9604
9605<div>
9606<div>
9607<pre class="source">{ &quot;a&quot;: &quot;+INF&quot;, &quot;b&quot;: 1 }
9608</pre></div></div>
9609</li>
9610</ul>
9611<p>The function has an alias <tt>posinfif</tt>.</p></div>
9612<div class="section">
9613<h3><a name="neginf_if_.28neginfif.29"></a>neginf_if (neginfif)</h3>
9614<ul>
9615
9616<li>
9617
9618<p>Syntax:</p>
9619
9620<div>
9621<div>
9622<pre class="source">neginf_if(expression1, expression2)
9623</pre></div></div>
9624</li>
9625<li>
9626
9627<p>Compares two arguments and returns <tt>-INF</tt> value if they are equal, otherwise returns the first argument.</p>
9628</li>
9629<li>Arguments:
9630<ul>
9631
9632<li><tt>expressionI</tt> : an expression (any type is allowed).</li>
9633</ul>
9634</li>
9635<li>Return Value:
9636<ul>
9637
9638<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
9639<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value</li>
9640<li><tt>-INF</tt> value of type <tt>double</tt> if <tt>argument1</tt> = <tt>argument2</tt></li>
9641<li>a value of the first argument otherwise</li>
9642</ul>
9643</li>
9644<li>
9645
9646<p>Example:</p>
9647
9648<div>
9649<div>
9650<pre class="source">{
9651 &quot;a&quot;: to_string(neginf_if(&quot;asterixdb&quot;, &quot;asterixdb&quot;)),
9652 &quot;b&quot;: neginf_if(1, 2)
9653};
9654</pre></div></div>
9655</li>
9656<li>
9657
9658<p>The expected result is:</p>
9659
9660<div>
9661<div>
9662<pre class="source">{ &quot;a&quot;: &quot;-INF&quot;, &quot;b&quot;: 1 }
9663</pre></div></div>
9664</li>
9665</ul>
9666<p>The function has an alias <tt>neginfif</tt>.</p><!--
9667 ! Licensed to the Apache Software Foundation (ASF) under one
9668 ! or more contributor license agreements. See the NOTICE file
9669 ! distributed with this work for additional information
9670 ! regarding copyright ownership. The ASF licenses this file
9671 ! to you under the Apache License, Version 2.0 (the
9672 ! "License"); you may not use this file except in compliance
9673 ! with the License. You may obtain a copy of the License at
9674 !
9675 ! http://www.apache.org/licenses/LICENSE-2.0
9676 !
9677 ! Unless required by applicable law or agreed to in writing,
9678 ! software distributed under the License is distributed on an
9679 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
9680 ! KIND, either express or implied. See the License for the
9681 ! specific language governing permissions and limitations
9682 ! under the License.
9683 !-->
9684</div></div>
9685<div class="section">
9686<h2><a name="Miscellaneous_Functions"></a><a name="MiscFunctions" id="MiscFunctions">Miscellaneous Functions</a></h2>
9687<div class="section">
9688<h3><a name="uuid"></a>uuid</h3>
9689<ul>
9690
9691<li>
9692
9693<p>Syntax:</p>
9694
9695<div>
9696<div>
9697<pre class="source">uuid()
9698</pre></div></div>
9699</li>
9700<li>
9701
9702<p>Generates a <tt>uuid</tt>.</p>
9703</li>
9704<li>Arguments:
9705<ul>
9706
9707<li>none</li>
9708</ul>
9709</li>
9710<li>Return Value:
9711<ul>
9712
9713<li>a generated, random <tt>uuid</tt>.</li>
9714</ul>
9715</li>
9716</ul></div>
9717<div class="section">
9718<h3><a name="len"></a>len</h3>
9719<ul>
9720
9721<li>
9722
9723<p>Syntax:</p>
9724<p>len(array)</p>
9725</li>
9726<li>
9727
9728<p>Returns the length of the array array.</p>
9729</li>
9730<li>Arguments:
9731<ul>
9732
9733<li><tt>array</tt> : an <tt>array</tt>, <tt>multiset</tt>, <tt>null</tt>, or <tt>missing</tt>, represents the collection that needs to be checked.</li>
9734</ul>
9735</li>
9736<li>Return Value:
9737<ul>
9738
9739<li>an <tt>integer</tt> that represents the length of input array or the size of the input multiset,</li>
9740<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
9741<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value.</li>
9742</ul>
9743</li>
9744<li>
9745
9746<p>Example:</p>
9747
9748<div>
9749<div>
9750<pre class="source">len([&quot;Hello&quot;, &quot;World&quot;])
9751</pre></div></div>
9752</li>
9753<li>
9754
9755<p>The expected result is:</p>
9756
9757<div>
9758<div>
9759<pre class="source">2
9760</pre></div></div>
9761</li>
9762</ul></div>
9763<div class="section">
9764<h3><a name="not"></a>not</h3>
9765<ul>
9766
9767<li>
9768
9769<p>Syntax:</p>
9770
9771<div>
9772<div>
9773<pre class="source">not(expr)
9774</pre></div></div>
9775</li>
9776<li>
9777
9778<p>Inverts a <tt>boolean</tt> value</p>
9779</li>
9780<li>Arguments:
9781<ul>
9782
9783<li><tt>expr</tt> : an expression</li>
9784</ul>
9785</li>
9786<li>Return Value:
9787<ul>
9788
9789<li>a <tt>boolean</tt>, the inverse of <tt>expr</tt>,</li>
9790<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
9791<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
9792<li>other non-boolean argument value will cause a type error.</li>
9793</ul>
9794</li>
9795<li>Example:
9796
9797<div>
9798<div>
9799<pre class="source">{ &quot;v1&quot;: `not`(true), &quot;v2&quot;: `not`(false), &quot;v3&quot;: `not`(null), &quot;v4&quot;: `not`(missing) };
9800</pre></div></div>
9801</li>
9802<li>
9803
9804<p>The expected result is:</p>
9805
9806<div>
9807<div>
9808<pre class="source">{ &quot;v1&quot;: false, &quot;v2&quot;: true, &quot;v3&quot;: null }
9809</pre></div></div>
9810</li>
9811</ul></div>
9812<div class="section">
9813<h3><a name="random"></a>random</h3>
9814<ul>
9815
9816<li>
9817
9818<p>Syntax:</p>
9819
9820<div>
9821<div>
9822<pre class="source">random( [seed_value] )
9823</pre></div></div>
9824</li>
9825<li>
9826
9827<p>Returns a random number, accepting an optional seed value</p>
9828</li>
9829<li>Arguments:
9830<ul>
9831
9832<li><tt>seed_value</tt>: an optional <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value representing the seed number.</li>
9833</ul>
9834</li>
9835<li>Return Value:
9836<ul>
9837
9838<li>A random number of type <tt>double</tt> between 0 and 1,</li>
9839<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
9840<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
9841<li>any other non-numeric input value will cause a type error.</li>
9842</ul>
9843</li>
9844<li>
9845
9846<p>Example:</p>
9847
9848<div>
9849<div>
9850<pre class="source">{
9851 &quot;v1&quot;: random(),
9852 &quot;v2&quot;: random(unix_time_from_datetime_in_ms(current_datetime()))
9853};
9854</pre></div></div>
9855</li>
9856</ul></div>
9857<div class="section">
9858<h3><a name="range"></a>range</h3>
9859<ul>
9860
9861<li>
9862
9863<p>Syntax:</p>
9864
9865<div>
9866<div>
9867<pre class="source">range(start_numeric_value, end_numeric_value)
9868</pre></div></div>
9869</li>
9870<li>
9871
9872<p>Generates a series of <tt>bigint</tt> values based start the <tt>start_numeric_value</tt> until the <tt>end_numeric_value</tt>.</p>
9873</li>
9874<li>Arguments:</li>
9875<li><tt>start_numeric_value</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt> value representing the start value.</li>
9876<li><tt>end_numeric_value</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt> value representing the max final value.</li>
9877<li>Return Value:
9878<ul>
9879
9880<li>an array that starts with the integer value of <tt>start_numeric_value</tt> and ends with the integer value of <tt>end_numeric_value</tt>, where the value of each entry in the array is the integer successor of the value in the preceding entry.</li>
9881</ul>
9882</li>
9883<li>Example:
9884
9885<div>
9886<div>
9887<pre class="source">range(0, 3);
9888</pre></div></div>
9889</li>
9890<li>
9891
9892<p>The expected result is:</p>
9893
9894<div>
9895<div>
9896<pre class="source">[ 0, 1, 2, 3 ]
9897</pre></div></div>
9898</li>
9899</ul></div>
9900<div class="section">
9901<h3><a name="switch_case"></a>switch_case</h3>
9902<ul>
9903
9904<li>
9905
9906<p>Syntax:</p>
9907
9908<div>
9909<div>
9910<pre class="source">switch_case(
9911 condition,
9912 case1, case1_result,
9913 case2, case2_result,
9914 ...,
9915 default, default_result
9916)
9917</pre></div></div>
9918</li>
9919<li>
9920
9921<p>Switches amongst a sequence of cases and returns the result of the first matching case. If no match is found, the result of the default case is returned.</p>
9922</li>
9923<li>Arguments:
9924<ul>
9925
9926<li><tt>condition</tt>: a variable (any type is allowed).</li>
9927<li><tt>caseI/default</tt>: a variable (any type is allowed).</li>
9928<li><tt>caseI/default_result</tt>: a variable (any type is allowed).</li>
9929</ul>
9930</li>
9931<li>Return Value:
9932<ul>
9933
9934<li><tt>caseI_result</tt> if <tt>condition</tt> matches <tt>caseI</tt>, otherwise <tt>default_result</tt>.</li>
9935</ul>
9936</li>
9937<li>Example 1:
9938
9939<div>
9940<div>
9941<pre class="source">switch_case(
9942 &quot;a&quot;,
9943 &quot;a&quot;, 0,
9944 &quot;x&quot;, 1,
9945 &quot;y&quot;, 2,
9946 &quot;z&quot;, 3
9947);
9948</pre></div></div>
9949</li>
9950<li>
9951
9952<p>The expected result is:</p>
9953
9954<div>
9955<div>
9956<pre class="source">0
9957</pre></div></div>
9958</li>
9959<li>
9960
9961<p>Example 2:</p>
9962
9963<div>
9964<div>
9965<pre class="source">switch_case(
9966 &quot;a&quot;,
9967 &quot;x&quot;, 1,
9968 &quot;y&quot;, 2,
9969 &quot;z&quot;, 3
9970);
9971</pre></div></div>
9972</li>
9973<li>
9974
9975<p>The expected result is:</p>
9976
9977<div>
9978<div>
9979<pre class="source">3
9980</pre></div></div>
9981</li>
9982</ul></div>
9983<div class="section">
9984<h3><a name="deep_equal"></a>deep_equal</h3>
9985<ul>
9986
9987<li>
9988
9989<p>Syntax:</p>
9990
9991<div>
9992<div>
9993<pre class="source">deep_equal(expr1, expr2)
9994</pre></div></div>
9995</li>
9996<li>
9997
9998<p>Assess the equality between two expressions of any type (e.g., object, arrays, or multiset). Two objects are deeply equal iff both their types and values are equal.</p>
9999</li>
10000<li>Arguments:
10001<ul>
10002
10003<li><tt>expr1</tt> : an expression,</li>
10004<li><tt>expr2</tt> : an expression.</li>
10005</ul>
10006</li>
10007<li>Return Value:
10008<ul>
10009
10010<li><tt>true</tt> or <tt>false</tt> depending on the data equality,</li>
10011<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
10012<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value.</li>
10013</ul>
10014</li>
10015<li>
10016
10017<p>Example:</p>
10018
10019<div>
10020<div>
10021<pre class="source">deep_equal(
10022 {
10023 &quot;id&quot;:1,
10024 &quot;project&quot;:&quot;AsterixDB&quot;,
10025 &quot;address&quot;:{&quot;city&quot;:&quot;Irvine&quot;, &quot;state&quot;:&quot;CA&quot;},
10026 &quot;related&quot;:[&quot;Hivestrix&quot;, &quot;Preglix&quot;, &quot;Apache VXQuery&quot;]
10027 },
10028 {
10029 &quot;id&quot;:1,
10030 &quot;project&quot;:&quot;AsterixDB&quot;,
10031 &quot;address&quot;:{&quot;city&quot;:&quot;San Diego&quot;, &quot;state&quot;:&quot;CA&quot;},
10032 &quot;related&quot;:[&quot;Hivestrix&quot;, &quot;Preglix&quot;, &quot;Apache VXQuery&quot;]
10033 }
10034);
10035</pre></div></div>
10036</li>
10037<li>
10038
10039<p>The expected result is:</p>
10040
10041<div>
10042<div>
10043<pre class="source">false
10044</pre></div></div>
10045</li>
10046</ul></div></div>
10047 </div>
10048 </div>
10049 </div>
10050 <hr/>
10051 <footer>
10052 <div class="container-fluid">
10053 <div class="row-fluid">
10054<div class="row-fluid">Apache AsterixDB, AsterixDB, Apache, the Apache
10055 feather logo, and the Apache AsterixDB project logo are either
10056 registered trademarks or trademarks of The Apache Software
10057 Foundation in the United States and other countries.
10058 All other marks mentioned may be trademarks or registered
10059 trademarks of their respective owners.
10060 </div>
10061 </div>
10062 </div>
10063 </footer>
10064 </body>
10065</html>