Gitiles
Code Review Sign In
asterix-gerrit.ics.uci.edu / incubator-asterixdb-site / 5f34114603bb17e7c3493d060d88bad69e418cda / . / content / docs / 0.9.2 / aql / builtins.html
blob: 98e9d8b1c4c892d13e892c4951aa73503290b69d [file] [log] [blame]
Ian Maxon7a4bed92017-09-15 02:01:18 +0200[diff] [blame]1<!DOCTYPE html>
2<!--
3 | Generated by Apache Maven Doxia at 2017-09-14
4 | Rendered using Apache Maven Fluido Skin 1.3.0
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="20170914" />
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.3.0.min.css" />
14 <link rel="stylesheet" href="../css/site.css" />
15 <link rel="stylesheet" href="../css/print.css" media="print" />
16
17
18 <script type="text/javascript" src="../js/apache-maven-fluido-1.3.0.min.js"></script>
19
20
21
Ian Maxon7a4bed92017-09-15 02:01:18 +0200[diff] [blame]22
Ian Maxon7a4bed92017-09-15 02:01:18 +0200[diff] [blame]23
24 </head>
25 <body class="topBarDisabled">
26
27
28
29
30 <div class="container-fluid">
31 <div id="banner">
32 <div class="pull-left">
33 <a href=".././" id="bannerLeft">
34 <img src="../images/asterixlogo.png" alt="AsterixDB"/>
35 </a>
36 </div>
37 <div class="pull-right"> </div>
38 <div class="clear"><hr/></div>
39 </div>
40
41 <div id="breadcrumbs">
42 <ul class="breadcrumb">
43
44
45 <li id="publishDate">Last Published: 2017-09-14</li>
46
47
48
49 <li id="projectVersion" class="pull-right">Version: 0.9.2</li>
50
51 <li class="divider pull-right">|</li>
52
53 <li class="pull-right"> <a href="../index.html" title="Documentation Home">
54 Documentation Home</a>
55 </li>
56
57 </ul>
58 </div>
59
60
61 <div class="row-fluid">
62 <div id="leftColumn" class="span3">
63 <div class="well sidebar-nav">
64
65
66 <ul class="nav nav-list">
67 <li class="nav-header">Get Started - Installation</li>
68
69 <li>
70
71 <a href="../ncservice.html" title="Option 1: using NCService">
72 <i class="none"></i>
73 Option 1: using NCService</a>
74 </li>
75
76 <li>
77
78 <a href="../ansible.html" title="Option 2: using Ansible">
79 <i class="none"></i>
80 Option 2: using Ansible</a>
81 </li>
82
83 <li>
84
85 <a href="../aws.html" title="Option 3: using Amazon Web Services">
86 <i class="none"></i>
87 Option 3: using Amazon Web Services</a>
88 </li>
89
90 <li>
91
92 <a href="../yarn.html" title="Option 4: using YARN">
93 <i class="none"></i>
94 Option 4: using YARN</a>
95 </li>
96
97 <li>
98
99 <a href="../install.html" title="Option 5: using Managix (deprecated)">
100 <i class="none"></i>
101 Option 5: using Managix (deprecated)</a>
102 </li>
103 <li class="nav-header">AsterixDB Primer</li>
104
105 <li>
106
107 <a href="../sqlpp/primer-sqlpp.html" title="Option 1: using SQL++">
108 <i class="none"></i>
109 Option 1: using SQL++</a>
110 </li>
111
112 <li>
113
114 <a href="../aql/primer.html" title="Option 2: using AQL">
115 <i class="none"></i>
116 Option 2: using AQL</a>
117 </li>
118 <li class="nav-header">Data Model</li>
119
120 <li>
121
122 <a href="../datamodel.html" title="The Asterix Data Model">
123 <i class="none"></i>
124 The Asterix Data Model</a>
125 </li>
126 <li class="nav-header">Queries - SQL++</li>
127
128 <li>
129
130 <a href="../sqlpp/manual.html" title="The SQL++ Query Language">
131 <i class="none"></i>
132 The SQL++ Query Language</a>
133 </li>
134
135 <li>
136
137 <a href="../sqlpp/builtins.html" title="Builtin Functions">
138 <i class="none"></i>
139 Builtin Functions</a>
140 </li>
141 <li class="nav-header">Queries - AQL</li>
142
143 <li>
144
145 <a href="../aql/manual.html" title="The Asterix Query Language (AQL)">
146 <i class="none"></i>
147 The Asterix Query Language (AQL)</a>
148 </li>
149
150 <li class="active">
151
152 <a href="#"><i class="none"></i>Builtin Functions</a>
153 </li>
154 <li class="nav-header">API/SDK</li>
155
156 <li>
157
158 <a href="../api.html" title="HTTP API">
159 <i class="none"></i>
160 HTTP API</a>
161 </li>
162
163 <li>
164
165 <a href="../csv.html" title="CSV Output">
166 <i class="none"></i>
167 CSV Output</a>
168 </li>
169 <li class="nav-header">Advanced Features</li>
170
171 <li>
172
173 <a href="../aql/fulltext.html" title="Support of Full-text Queries">
174 <i class="none"></i>
175 Support of Full-text Queries</a>
176 </li>
177
178 <li>
179
180 <a href="../aql/externaldata.html" title="Accessing External Data">
181 <i class="none"></i>
182 Accessing External Data</a>
183 </li>
184
185 <li>
186
187 <a href="../feeds/tutorial.html" title="Support for Data Ingestion">
188 <i class="none"></i>
189 Support for Data Ingestion</a>
190 </li>
191
192 <li>
193
194 <a href="../udf.html" title="User Defined Functions">
195 <i class="none"></i>
196 User Defined Functions</a>
197 </li>
198
199 <li>
200
201 <a href="../aql/filters.html" title="Filter-Based LSM Index Acceleration">
202 <i class="none"></i>
203 Filter-Based LSM Index Acceleration</a>
204 </li>
205
206 <li>
207
208 <a href="../aql/similarity.html" title="Support of Similarity Queries">
209 <i class="none"></i>
210 Support of Similarity Queries</a>
211 </li>
212 </ul>
213
214
215
216 <hr class="divider" />
217
218 <div id="poweredBy">
219 <div class="clear"></div>
220 <div class="clear"></div>
221 <div class="clear"></div>
222 <a href=".././" title="AsterixDB" class="builtBy">
223 <img class="builtBy" alt="AsterixDB" src="../images/asterixlogo.png" />
224 </a>
225 </div>
226 </div>
227 </div>
228
229
230 <div id="bodyColumn" class="span9" >
231
232 <!-- ! Licensed to the Apache Software Foundation (ASF) under one
233 ! or more contributor license agreements. See the NOTICE file
234 ! distributed with this work for additional information
235 ! regarding copyright ownership. The ASF licenses this file
236 ! to you under the Apache License, Version 2.0 (the
237 ! "License"); you may not use this file except in compliance
238 ! with the License. You may obtain a copy of the License at
239 !
240 ! http://www.apache.org/licenses/LICENSE-2.0
241 !
242 ! Unless required by applicable law or agreed to in writing,
243 ! software distributed under the License is distributed on an
244 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
245 ! KIND, either express or implied. See the License for the
246 ! specific language governing permissions and limitations
247 ! under the License.
248 ! --><h1>Builtin Functions</h1>
249<div class="section">
250<h2><a name="Table_of_Contents"></a><a name="toc" id="toc">Table of Contents</a></h2>
251
252<ul>
253
254<li><a href="#NumericFunctions">Numeric Functions</a></li>
255
256<li><a href="#StringFunctions">String Functions</a></li>
257
258<li><a href="#BinaryFunctions">Binary Functions</a></li>
259
260<li><a href="#SpatialFunctions">Spatial Functions</a></li>
261
262<li><a href="#SimilarityFunctions">Similarity Functions</a></li>
263
264<li><a href="#TokenizingFunctions">Tokenizing Functions</a></li>
265
266<li><a href="#TemporalFunctions">Temporal Functions</a></li>
267
268<li><a href="#ObjectFunctions">Object Functions</a></li>
269
270<li><a href="#AggregateFunctions">Aggregate Functions (Array Functions)</a></li>
271
272<li><a href="#ComparisonFunctions">Comparison Functions</a></li>
273
274<li><a href="#TypeFunctions">Type Functions</a></li>
275
276<li><a href="#ConditionalFunctions">Conditional Functions</a></li>
277
278<li><a href="#MiscFunctions">Miscellaneous Functions</a></li>
279</ul>
280<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. <!-- ! Licensed to the Apache Software Foundation (ASF) under one
281 ! or more contributor license agreements. See the NOTICE file
282 ! distributed with this work for additional information
283 ! regarding copyright ownership. The ASF licenses this file
284 ! to you under the Apache License, Version 2.0 (the
285 ! "License"); you may not use this file except in compliance
286 ! with the License. You may obtain a copy of the License at
287 !
288 ! http://www.apache.org/licenses/LICENSE-2.0
289 !
290 ! Unless required by applicable law or agreed to in writing,
291 ! software distributed under the License is distributed on an
292 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
293 ! KIND, either express or implied. See the License for the
294 ! specific language governing permissions and limitations
295 ! under the License.
296 ! --></p></div>
297<div class="section">
298<h2><a name="Numeric_Functions"></a><a name="NumericFunctions" id="NumericFunctions">Numeric Functions</a></h2>
299<div class="section">
300<h3><a name="abs"></a>abs</h3>
301
302<ul>
303
304<li>
305<p>Syntax:</p>
306
307<div class="source">
308<div class="source">
309<pre>abs(numeric_value)
310</pre></div></div></li>
311
312<li>
313<p>Computes the absolute value of the argument.</p></li>
314
315<li>Arguments:
316
317<ul>
318
319<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>
320 </ul></li>
321
322<li>Return Value:
323
324<ul>
325
326<li>The absolute value of the argument with the same type as the input argument,</li>
327
328<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
329
330<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
331
332<li>any other non-numeric input value will cause a type error.</li>
333 </ul></li>
334
335<li>
336<p>Example:</p>
337
338<div class="source">
339<div class="source">
340<pre>{ &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;)) };
341</pre></div></div></li>
342</ul>
343
344<ul>
345
346<li>
347<p>The expected result is:</p>
348
349<div class="source">
350<div class="source">
351<pre>{ &quot;v1&quot;: 2013, &quot;v2&quot;: 4036, &quot;v3&quot;: 0, &quot;v4&quot;: 2013.5, &quot;v5&quot;: 2013.5938237483274 }
352</pre></div></div></li>
353</ul></div>
354<div class="section">
355<h3><a name="acos"></a>acos</h3>
356
357<ul>
358
359<li>
360<p>Syntax:</p>
361
362<div class="source">
363<div class="source">
364<pre>acos(numeric_value)
365</pre></div></div></li>
366
367<li>
368<p>Computes the arc cosine value of the argument.</p></li>
369
370<li>Arguments:
371
372<ul>
373
374<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>
375 </ul></li>
376
377<li>Return Value:
378
379<ul>
380
381<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>
382
383<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
384
385<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
386
387<li>any other non-numeric input value will cause a type error,</li>
388
389<li>&#x201c;NaN&#x201d; for other legitimate numeric values.</li>
390 </ul></li>
391
392<li>
393<p>Example:</p>
394
395<div class="source">
396<div class="source">
397<pre>{ &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;)) };
398</pre></div></div></li>
399</ul>
400
401<ul>
402
403<li>
404<p>The expected result is:</p>
405
406<div class="source">
407<div class="source">
408<pre>{ &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 }
409</pre></div></div></li>
410</ul></div>
411<div class="section">
412<h3><a name="asin"></a>asin</h3>
413
414<ul>
415
416<li>
417<p>Syntax:</p>
418
419<div class="source">
420<div class="source">
421<pre>asin(numeric_value)
422</pre></div></div></li>
423
424<li>
425<p>Computes the arc sine value of the argument.</p></li>
426
427<li>Arguments:
428
429<ul>
430
431<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>
432 </ul></li>
433
434<li>Return Value:
435
436<ul>
437
438<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>
439
440<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
441
442<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
443
444<li>any other non-numeric input value will cause a type error,</li>
445
446<li>&#x201c;NaN&#x201d; for other legitimate numeric values.</li>
447 </ul></li>
448
449<li>
450<p>Example:</p>
451
452<div class="source">
453<div class="source">
454<pre>{ &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;)) };
455</pre></div></div></li>
456</ul>
457
458<ul>
459
460<li>
461<p>The expected result is:</p>
462
463<div class="source">
464<div class="source">
465<pre>{ &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 }
466</pre></div></div></li>
467</ul></div>
468<div class="section">
469<h3><a name="atan"></a>atan</h3>
470
471<ul>
472
473<li>
474<p>Syntax:</p>
475
476<div class="source">
477<div class="source">
478<pre>atan(numeric_value)
479</pre></div></div></li>
480
481<li>
482<p>Computes the arc tangent value of the argument.</p></li>
483
484<li>Arguments:
485
486<ul>
487
488<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>
489 </ul></li>
490
491<li>Return Value:
492
493<ul>
494
495<li>the <tt>double</tt> arc tangent in radians for the argument,</li>
496
497<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
498
499<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
500
501<li>any other non-numeric input value will cause a type error.</li>
502 </ul></li>
503
504<li>
505<p>Example:</p>
506
507<div class="source">
508<div class="source">
509<pre>{ &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;)) };
510</pre></div></div></li>
511</ul>
512
513<ul>
514
515<li>
516<p>The expected result is:</p>
517
518<div class="source">
519<div class="source">
520<pre>{ &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 }
521</pre></div></div></li>
522</ul></div>
523<div class="section">
524<h3><a name="atan2"></a>atan2</h3>
525
526<ul>
527
528<li>
529<p>Syntax:</p>
530
531<div class="source">
532<div class="source">
533<pre>atan2(numeric_value1, numeric_value2)
534</pre></div></div></li>
535
536<li>
537<p>Computes the arc tangent value of numeric_value2/numeric_value1.</p></li>
538
539<li>Arguments:
540
541<ul>
542
543<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>
544
545<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>
546 </ul></li>
547
548<li>Return Value:
549
550<ul>
551
552<li>the <tt>double</tt> arc tangent in radians for <tt>numeric_value1</tt> and <tt>numeric_value2</tt>,</li>
553
554<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
555
556<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
557
558<li>any other non-numeric input value will cause a type error.</li>
559 </ul></li>
560
561<li>
562<p>Example:</p>
563
564<div class="source">
565<div class="source">
566<pre>{ &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;)) };
567</pre></div></div></li>
568</ul>
569
570<ul>
571
572<li>
573<p>The expected result is:</p>
574
575<div class="source">
576<div class="source">
577<pre>{ &quot;v1&quot;: 0.4636476090008061, &quot;v2&quot;: 0.0, &quot;v3&quot;: 2.356194490192345 }
578</pre></div></div></li>
579</ul></div>
580<div class="section">
581<h3><a name="ceil"></a>ceil</h3>
582
583<ul>
584
585<li>
586<p>Syntax:</p>
587
588<div class="source">
589<div class="source">
590<pre>ceil(numeric_value)
591</pre></div></div></li>
592
593<li>
594<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></li>
595
596<li>Arguments:
597
598<ul>
599
600<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>
601 </ul></li>
602
603<li>Return Value:
604
605<ul>
606
607<li>The ceiling value for the given number in the same type as the input argument,</li>
608
609<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
610
611<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
612
613<li>any other non-numeric input value will cause a type error.</li>
614 </ul></li>
615
616<li>
617<p>Example:</p>
618
619<div class="source">
620<div class="source">
621<pre>{
622 &quot;v1&quot;: ceil(2013),
623 &quot;v2&quot;: ceil(-4036),
624 &quot;v3&quot;: ceil(0.3),
625 &quot;v4&quot;: ceil(float(&quot;-2013.2&quot;)),
626 &quot;v5&quot;: ceil(double(&quot;-2013.893823748327284&quot;))
627};
628</pre></div></div></li>
629</ul>
630
631<ul>
632
633<li>
634<p>The expected result is:</p>
635
636<div class="source">
637<div class="source">
638<pre>{ &quot;v1&quot;: 2013, &quot;v2&quot;: -4036, &quot;v3&quot;: 1.0, &quot;v4&quot;: -2013.0, &quot;v5&quot;: -2013.0 }
639</pre></div></div></li>
640</ul></div>
641<div class="section">
642<h3><a name="cos"></a>cos</h3>
643
644<ul>
645
646<li>
647<p>Syntax:</p>
648
649<div class="source">
650<div class="source">
651<pre>cos(numeric_value)
652</pre></div></div></li>
653
654<li>
655<p>Computes the cosine value of the argument.</p></li>
656
657<li>Arguments:
658
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></li>
663
664<li>Return Value:
665
666<ul>
667
668<li>the <tt>double</tt> cosine value for the argument,</li>
669
670<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
671
672<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
673
674<li>any other non-numeric input value will cause a type error.</li>
675 </ul></li>
676
677<li>
678<p>Example:</p>
679
680<div class="source">
681<div class="source">
682<pre>{ &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;)) };
683</pre></div></div></li>
684</ul>
685
686<ul>
687
688<li>
689<p>The expected result is:</p>
690
691<div class="source">
692<div class="source">
693<pre>{ &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 }
694</pre></div></div></li>
695</ul></div>
696<div class="section">
697<h3><a name="exp"></a>exp</h3>
698
699<ul>
700
701<li>
702<p>Syntax:</p>
703
704<div class="source">
705<div class="source">
706<pre>exp(numeric_value)
707</pre></div></div></li>
708
709<li>
710<p>Computes e<sup>numeric_value</sup>.</p></li>
711
712<li>Arguments:
713
714<ul>
715
716<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>
717 </ul></li>
718
719<li>Return Value:
720
721<ul>
722
723<li>e<sup>numeric_value</sup>,</li>
724
725<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
726
727<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
728
729<li>any other non-numeric input value will cause a type error.</li>
730 </ul></li>
731
732<li>
733<p>Example:</p>
734
735<div class="source">
736<div class="source">
737<pre>{ &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;)) };
738</pre></div></div></li>
739</ul>
740
741<ul>
742
743<li>
744<p>The expected result is:</p>
745
746<div class="source">
747<div class="source">
748<pre>{ &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; }
749</pre></div></div></li>
750</ul></div>
751<div class="section">
752<h3><a name="floor"></a>floor</h3>
753
754<ul>
755
756<li>
757<p>Syntax:</p>
758
759<div class="source">
760<div class="source">
761<pre>floor(numeric_value)
762</pre></div></div></li>
763
764<li>
765<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></li>
766
767<li>Arguments:
768
769<ul>
770
771<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>
772 </ul></li>
773
774<li>Return Value:
775
776<ul>
777
778<li>The floor value for the given number in the same type as the input argument,</li>
779
780<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
781
782<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
783
784<li>any other non-numeric input value will cause a type error.</li>
785 </ul></li>
786
787<li>
788<p>Example:</p>
789
790<div class="source">
791<div class="source">
792<pre>{
793 &quot;v1&quot;: floor(2013),
794 &quot;v2&quot;: floor(-4036),
795 &quot;v3&quot;: floor(0.8),
796 &quot;v4&quot;: floor(float(&quot;-2013.2&quot;)),
797 &quot;v5&quot;: floor(double(&quot;-2013.893823748327284&quot;))
798};
799</pre></div></div></li>
800</ul>
801
802<ul>
803
804<li>
805<p>The expected result is:</p>
806
807<div class="source">
808<div class="source">
809<pre>{ &quot;v1&quot;: 2013, &quot;v2&quot;: -4036, &quot;v3&quot;: 0.0, &quot;v4&quot;: -2014.0, &quot;v5&quot;: -2014.0 }
810</pre></div></div></li>
811</ul></div>
812<div class="section">
813<h3><a name="ln"></a>ln</h3>
814
815<ul>
816
817<li>
818<p>Syntax:</p>
819
820<div class="source">
821<div class="source">
822<pre>ln(numeric_value)
823</pre></div></div></li>
824
825<li>
826<p>Computes log<sub>e</sub>numeric_value.</p></li>
827
828<li>Arguments:
829
830<ul>
831
832<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>
833 </ul></li>
834
835<li>Return Value:
836
837<ul>
838
839<li>log<sub>e</sub>numeric_value,</li>
840
841<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
842
843<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
844
845<li>any other non-numeric input value will cause a type error.</li>
846 </ul></li>
847
848<li>
849<p>Example:</p>
850
851<div class="source">
852<div class="source">
853<pre>{ &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;)) };
854</pre></div></div></li>
855</ul>
856
857<ul>
858
859<li>
860<p>The expected result is:</p>
861
862<div class="source">
863<div class="source">
864<pre>{ &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 }
865</pre></div></div></li>
866</ul></div>
867<div class="section">
868<h3><a name="log"></a>log</h3>
869
870<ul>
871
872<li>
873<p>Syntax:</p>
874
875<div class="source">
876<div class="source">
877<pre>log(numeric_value)
878</pre></div></div></li>
879
880<li>
881<p>Computes log<sub>10</sub>numeric_value.</p></li>
882
883<li>Arguments:
884
885<ul>
886
887<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>
888 </ul></li>
889
890<li>Return Value:
891
892<ul>
893
894<li>log<sub>10</sub>numeric_value,</li>
895
896<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
897
898<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
899
900<li>any other non-numeric input value will cause a type error.</li>
901 </ul></li>
902
903<li>
904<p>Example:</p>
905
906<div class="source">
907<div class="source">
908<pre>{ &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;)) };
909</pre></div></div></li>
910
911<li>
912<p>The expected result is:</p>
913
914<div class="source">
915<div class="source">
916<pre>{ &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 }
917</pre></div></div></li>
918</ul></div>
919<div class="section">
920<h3><a name="power"></a>power</h3>
921
922<ul>
923
924<li>
925<p>Syntax:</p>
926
927<div class="source">
928<div class="source">
929<pre>power(numeric_value1, numeric_value2)
930</pre></div></div></li>
931
932<li>
933<p>Computes numeric_value1<sup>numeric_value2</sup>.</p></li>
934
935<li>Arguments:
936
937<ul>
938
939<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>
940
941<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>
942 </ul></li>
943
944<li>Return Value:
945
946<ul>
947
948<li>numeric_value1<sup>numeric_value2</sup>,</li>
949
950<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
951
952<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
953
954<li>any other non-numeric input value will cause a type error.</li>
955 </ul></li>
956
957<li>
958<p>Example:</p>
959
960<div class="source">
961<div class="source">
962<pre>{ &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;)) };
963</pre></div></div></li>
964</ul>
965
966<ul>
967
968<li>
969<p>The expected result is:</p>
970
971<div class="source">
972<div class="source">
973<pre>{ &quot;v1&quot;: 1, &quot;v3&quot;: 0, &quot;v4&quot;: 1.4142135623730951 }
974</pre></div></div></li>
975</ul></div>
976<div class="section">
977<h3><a name="round"></a>round</h3>
978
979<ul>
980
981<li>
982<p>Syntax:</p>
983
984<div class="source">
985<div class="source">
986<pre>round(numeric_value)
987</pre></div></div></li>
988
989<li>
990<p>Computes the number with no fractional part that is closest (and also closest to positive infinity) to the argument.</p></li>
991
992<li>Arguments:
993
994<ul>
995
996<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>
997 </ul></li>
998
999<li>Return Value:
1000
1001<ul>
1002
1003<li>The rounded value for the given number in the same type as the input argument,</li>
1004
1005<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
1006
1007<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
1008
1009<li>any other non-numeric input value will cause a type error.</li>
1010 </ul></li>
1011
1012<li>
1013<p>Example:</p>
1014
1015<div class="source">
1016<div class="source">
1017<pre>{
1018 &quot;v1&quot;: round(2013),
1019 &quot;v2&quot;: round(-4036),
1020 &quot;v3&quot;: round(0.8),
1021 &quot;v4&quot;: round(float(&quot;-2013.256&quot;)),
1022 &quot;v5&quot;: round(double(&quot;-2013.893823748327284&quot;))
1023};
1024</pre></div></div></li>
1025</ul>
1026
1027<ul>
1028
1029<li>
1030<p>The expected result is:</p>
1031
1032<div class="source">
1033<div class="source">
1034<pre>{ &quot;v1&quot;: 2013, &quot;v2&quot;: -4036, &quot;v3&quot;: 1.0, &quot;v4&quot;: -2013.0, &quot;v5&quot;: -2014.0 }
1035</pre></div></div></li>
1036</ul></div>
1037<div class="section">
1038<h3><a name="sign"></a>sign</h3>
1039
1040<ul>
1041
1042<li>
1043<p>Syntax:</p>
1044
1045<div class="source">
1046<div class="source">
1047<pre>sign(numeric_value)
1048</pre></div></div></li>
1049
1050<li>
1051<p>Computes the sign of the argument.</p></li>
1052
1053<li>Arguments:
1054
1055<ul>
1056
1057<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>
1058 </ul></li>
1059
1060<li>Return Value:
1061
1062<ul>
1063
1064<li>the sign (a <tt>tinyint</tt>) of the argument, -1 for negative values, 0 for 0, and 1 for positive values,</li>
1065
1066<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
1067
1068<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
1069
1070<li>any other non-numeric input value will cause a type error.</li>
1071 </ul></li>
1072
1073<li>
1074<p>Example:</p>
1075
1076<div class="source">
1077<div class="source">
1078<pre>{ &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;)) };
1079</pre></div></div></li>
1080</ul>
1081
1082<ul>
1083
1084<li>
1085<p>The expected result is:</p>
1086
1087<div class="source">
1088<div class="source">
1089<pre>{ &quot;v1&quot;: 1, &quot;v2&quot;: 1, &quot;v3&quot;: 0, &quot;v4&quot;: 1, &quot;v5&quot;: -1 }
1090</pre></div></div></li>
1091</ul></div>
1092<div class="section">
1093<h3><a name="sin"></a>sin</h3>
1094
1095<ul>
1096
1097<li>
1098<p>Syntax:</p>
1099
1100<div class="source">
1101<div class="source">
1102<pre>sin(numeric_value)
1103</pre></div></div></li>
1104
1105<li>
1106<p>Computes the sine value of the argument.</p></li>
1107
1108<li>Arguments:
1109
1110<ul>
1111
1112<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>
1113 </ul></li>
1114
1115<li>Return Value:
1116
1117<ul>
1118
1119<li>the <tt>double</tt> sine value for the argument,</li>
1120
1121<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
1122
1123<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
1124
1125<li>any other non-numeric input value will cause a type error.</li>
1126 </ul></li>
1127
1128<li>
1129<p>Example:</p>
1130
1131<div class="source">
1132<div class="source">
1133<pre>{ &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;)) };
1134</pre></div></div></li>
1135</ul>
1136
1137<ul>
1138
1139<li>
1140<p>The expected result is:</p>
1141
1142<div class="source">
1143<div class="source">
1144<pre>{ &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 }
1145</pre></div></div></li>
1146</ul></div>
1147<div class="section">
1148<h3><a name="sqrt"></a>sqrt</h3>
1149
1150<ul>
1151
1152<li>
1153<p>Syntax:</p>
1154
1155<div class="source">
1156<div class="source">
1157<pre>sqrt(numeric_value)
1158</pre></div></div></li>
1159
1160<li>
1161<p>Computes the square root of the argument.</p></li>
1162
1163<li>Arguments:
1164
1165<ul>
1166
1167<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>
1168 </ul></li>
1169
1170<li>Return Value:
1171
1172<ul>
1173
1174<li>the <tt>double</tt> square root value for the argument,</li>
1175
1176<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
1177
1178<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
1179
1180<li>any other non-numeric input value will cause a type error.</li>
1181 </ul></li>
1182
1183<li>
1184<p>Example:</p>
1185
1186<div class="source">
1187<div class="source">
1188<pre>{ &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;)) };
1189</pre></div></div></li>
1190</ul>
1191
1192<ul>
1193
1194<li>
1195<p>The expected result is:</p>
1196
1197<div class="source">
1198<div class="source">
1199<pre>{ &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 }
1200</pre></div></div></li>
1201</ul></div>
1202<div class="section">
1203<h3><a name="tan"></a>tan</h3>
1204
1205<ul>
1206
1207<li>
1208<p>Syntax:</p>
1209
1210<div class="source">
1211<div class="source">
1212<pre>tan(numeric_value)
1213</pre></div></div></li>
1214
1215<li>
1216<p>Computes the tangent value of the argument.</p></li>
1217
1218<li>Arguments:
1219
1220<ul>
1221
1222<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>
1223 </ul></li>
1224
1225<li>Return Value:
1226
1227<ul>
1228
1229<li>the <tt>double</tt> tangent value for the argument,</li>
1230
1231<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
1232
1233<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
1234
1235<li>any other non-numeric input value will cause a type error.</li>
1236 </ul></li>
1237
1238<li>
1239<p>Example:</p>
1240
1241<div class="source">
1242<div class="source">
1243<pre>{ &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;)) };
1244</pre></div></div></li>
1245</ul>
1246
1247<ul>
1248
1249<li>
1250<p>The expected result is:</p>
1251
1252<div class="source">
1253<div class="source">
1254<pre>{ &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 }
1255</pre></div></div></li>
1256</ul></div>
1257<div class="section">
1258<h3><a name="trunc"></a>trunc</h3>
1259
1260<ul>
1261
1262<li>
1263<p>Syntax:</p>
1264
1265<div class="source">
1266<div class="source">
1267<pre>trunc(numeric_value, number_digits)
1268</pre></div></div></li>
1269
1270<li>
1271<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></li>
1272
1273<li>Arguments:
1274
1275<ul>
1276
1277<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>
1278
1279<li><tt>number_digits</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt> value.</li>
1280 </ul></li>
1281
1282<li>Return Value:
1283
1284<ul>
1285
1286<li>the <tt>double</tt> tangent value for the argument,</li>
1287
1288<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
1289
1290<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is <tt>missing</tt>,</li>
1291
1292<li>a type error will be raised if:
1293
1294<ul>
1295
1296<li>the first argument is any other non-numeric value,</li>
1297
1298<li>the second argument is any other non-tinyint, non-smallint, non-integer, and non-bigint value.</li>
1299 </ul></li>
1300 </ul></li>
1301
1302<li>
1303<p>Example:</p>
1304
1305<div class="source">
1306<div class="source">
1307<pre>{ &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) };
1308</pre></div></div></li>
1309</ul>
1310
1311<ul>
1312
1313<li>
1314<p>The expected result is:</p>
1315
1316<div class="source">
1317<div class="source">
1318<pre>{ &quot;v1&quot;: 1, &quot;v2&quot;: 2, &quot;v3&quot;: 0.12, &quot;v4&quot;: 10.0, &quot;v5&quot;: 1000.525 }
1319</pre></div></div></li>
1320</ul>
1321<!-- ! Licensed to the Apache Software Foundation (ASF) under one
1322 ! or more contributor license agreements. See the NOTICE file
1323 ! distributed with this work for additional information
1324 ! regarding copyright ownership. The ASF licenses this file
1325 ! to you under the Apache License, Version 2.0 (the
1326 ! "License"); you may not use this file except in compliance
1327 ! with the License. You may obtain a copy of the License at
1328 !
1329 ! http://www.apache.org/licenses/LICENSE-2.0
1330 !
1331 ! Unless required by applicable law or agreed to in writing,
1332 ! software distributed under the License is distributed on an
1333 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
1334 ! KIND, either express or implied. See the License for the
1335 ! specific language governing permissions and limitations
1336 ! under the License.
1337 ! --></div>
1338<div class="section">
1339<h3><a name="round_half_to_even"></a>round_half_to_even</h3>
1340
1341<ul>
1342
1343<li>
1344<p>Syntax:</p>
1345
1346<div class="source">
1347<div class="source">
1348<pre>round_half_to_even(numeric_value, [precision])
1349</pre></div></div></li>
1350
1351<li>
1352<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></li>
1353
1354<li>Arguments:
1355
1356<ul>
1357
1358<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>
1359
1360<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>
1361 </ul></li>
1362
1363<li>Return Value:
1364
1365<ul>
1366
1367<li>The rounded value for the given number in the same type as the input argument,</li>
1368
1369<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
1370
1371<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
1372
1373<li>a type error will be raised if:
1374
1375<ul>
1376
1377<li>the first argument is any other non-numeric value,</li>
1378
1379<li>or, the second argument is any other non-tinyint, non-smallint, non-integer, or non-bigint value.</li>
1380 </ul></li>
1381 </ul></li>
1382
1383<li>
1384<p>Example:</p>
1385
1386<div class="source">
1387<div class="source">
1388<pre>{
1389 &quot;v1&quot;: round_half_to_even(2013),
1390 &quot;v2&quot;: round_half_to_even(-4036),
1391 &quot;v3&quot;: round_half_to_even(0.8),
1392 &quot;v4&quot;: round_half_to_even(float(&quot;-2013.256&quot;)),
1393 &quot;v5&quot;: round_half_to_even(double(&quot;-2013.893823748327284&quot;)),
1394 &quot;v6&quot;: round_half_to_even(double(&quot;-2013.893823748327284&quot;), 2),
1395 &quot;v7&quot;: round_half_to_even(2013, 4),
1396 &quot;v8&quot;: round_half_to_even(float(&quot;-2013.256&quot;), 5)
1397};
1398</pre></div></div></li>
1399</ul>
1400
1401<ul>
1402
1403<li>
1404<p>The expected result is:</p>
1405
1406<div class="source">
1407<div class="source">
1408<pre>{ &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 }
1409</pre></div></div></li>
1410</ul>
1411<!-- ! Licensed to the Apache Software Foundation (ASF) under one
1412 ! or more contributor license agreements. See the NOTICE file
1413 ! distributed with this work for additional information
1414 ! regarding copyright ownership. The ASF licenses this file
1415 ! to you under the Apache License, Version 2.0 (the
1416 ! "License"); you may not use this file except in compliance
1417 ! with the License. You may obtain a copy of the License at
1418 !
1419 ! http://www.apache.org/licenses/LICENSE-2.0
1420 !
1421 ! Unless required by applicable law or agreed to in writing,
1422 ! software distributed under the License is distributed on an
1423 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
1424 ! KIND, either express or implied. See the License for the
1425 ! specific language governing permissions and limitations
1426 ! under the License.
1427 ! --></div></div>
1428<div class="section">
1429<h2><a name="String_Functions"></a><a name="StringFunctions" id="StringFunctions">String Functions</a></h2>
1430<div class="section">
1431<h3><a name="concat"></a>concat</h3>
1432
1433<ul>
1434
1435<li>
1436<p>Syntax:</p>
1437
1438<div class="source">
1439<div class="source">
1440<pre>concat(string1, string2, ...)
1441</pre></div></div></li>
1442
1443<li>
1444<p>Returns a concatenated string from arguments.</p></li>
1445
1446<li>Arguments:
1447
1448<ul>
1449
1450<li><tt>string1</tt>: a string value,</li>
1451
1452<li><tt>string2</tt>: a string value,</li>
1453
1454<li>&#x2026;.</li>
1455 </ul></li>
1456
1457<li>Return Value:
1458
1459<ul>
1460
1461<li>a concatenated string from arguments,</li>
1462
1463<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
1464
1465<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
1466
1467<li>any other non-string input value will cause a type error.</li>
1468 </ul></li>
1469
1470<li>
1471<p>Example:</p>
1472
1473<div class="source">
1474<div class="source">
1475<pre>concat(&quot;test &quot;, &quot;driven &quot;, &quot;development&quot;);
1476</pre></div></div></li>
1477</ul>
1478
1479<ul>
1480
1481<li>
1482<p>The expected result is:</p>
1483
1484<div class="source">
1485<div class="source">
1486<pre>&quot;test driven development&quot;
1487</pre></div></div></li>
1488</ul></div>
1489<div class="section">
1490<h3><a name="contains"></a>contains</h3>
1491
1492<ul>
1493
1494<li>
1495<p>Syntax:</p>
1496
1497<div class="source">
1498<div class="source">
1499<pre>contains(string, substring_to_contain)
1500</pre></div></div></li>
1501
1502<li>
1503<p>Checks whether the string <tt>string</tt> contains the string <tt>substring_to_contain</tt></p></li>
1504
1505<li>Arguments:
1506
1507<ul>
1508
1509<li><tt>string</tt> : a <tt>string</tt> that might contain the given substring,</li>
1510
1511<li><tt>substring_to_contain</tt> : a target <tt>string</tt> that might be contained.</li>
1512 </ul></li>
1513
1514<li>Return Value:
1515
1516<ul>
1517
1518<li>a <tt>boolean</tt> value, <tt>true</tt> if <tt>string</tt> contains <tt>substring_to_contain</tt>,</li>
1519
1520<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
1521
1522<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
1523
1524<li>any other non-string input value will cause a type error,</li>
1525
1526<li><tt>false</tt> otherwise.</li>
1527 </ul></li>
1528
1529<li>
1530<p>Note: an <a href="similarity.html#UsingIndexesToSupportSimilarityQueries">n_gram index</a> can be utilized for this function.</p></li>
1531
1532<li>
1533<p>Example:</p>
1534
1535<div class="source">
1536<div class="source">
1537<pre>{ &quot;v1&quot;: contains(&quot;I like x-phone&quot;, &quot;phone&quot;), &quot;v2&quot;: contains(&quot;one&quot;, &quot;phone&quot;) };
1538</pre></div></div></li>
1539</ul>
1540
1541<ul>
1542
1543<li>
1544<p>The expected result is:</p>
1545
1546<div class="source">
1547<div class="source">
1548<pre>{ &quot;v1&quot;: true, &quot;v2&quot;: false }
1549</pre></div></div></li>
1550</ul></div>
1551<div class="section">
1552<h3><a name="ends_with"></a>ends_with</h3>
1553
1554<ul>
1555
1556<li>
1557<p>Syntax:</p>
1558
1559<div class="source">
1560<div class="source">
1561<pre>ends_with(string, substring_to_end_with)
1562</pre></div></div></li>
1563
1564<li>
1565<p>Checks whether the string <tt>string</tt> ends with the string <tt>substring_to_end_with</tt>.</p></li>
1566
1567<li>Arguments:
1568
1569<ul>
1570
1571<li><tt>string</tt> : a <tt>string</tt> that might end with the given string,</li>
1572
1573<li><tt>substring_to_end_with</tt> : a <tt>string</tt> that might be contained as the ending substring.</li>
1574 </ul></li>
1575
1576<li>Return Value:
1577
1578<ul>
1579
1580<li>a <tt>boolean</tt> value, <tt>true</tt> if <tt>string</tt> contains <tt>substring_to_contain</tt>,</li>
1581
1582<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
1583
1584<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
1585
1586<li>any other non-string input value will cause a type error,</li>
1587
1588<li><tt>false</tt> otherwise.</li>
1589 </ul></li>
1590
1591<li>
1592<p>Example:</p>
1593
1594<div class="source">
1595<div class="source">
1596<pre>{
1597 &quot;v1&quot;: ends_with(&quot; love product-b its shortcut_menu is awesome:)&quot;, &quot;:)&quot;),
1598 &quot;v2&quot;: ends_with(&quot; awsome:)&quot;, &quot;:-)&quot;)
1599};
1600</pre></div></div></li>
1601</ul>
1602
1603<ul>
1604
1605<li>
1606<p>The expected result is:</p>
1607
1608<div class="source">
1609<div class="source">
1610<pre>{ &quot;v1&quot;: true, &quot;v2&quot;: false }
1611</pre></div></div></li>
1612</ul></div>
1613<div class="section">
1614<h3><a name="initcap_or_title"></a>initcap (or title)</h3>
1615
1616<ul>
1617
1618<li>
1619<p>Syntax:</p>
1620
1621<div class="source">
1622<div class="source">
1623<pre>initcap(string)
1624</pre></div></div></li>
1625
1626<li>
1627<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></li>
1628
1629<li>Arguments:
1630
1631<ul>
1632
1633<li><tt>string</tt> : a <tt>string</tt> to be converted.</li>
1634 </ul></li>
1635
1636<li>Return Value:
1637
1638<ul>
1639
1640<li>a <tt>string</tt> as the title form of the given <tt>string</tt>,</li>
1641
1642<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
1643
1644<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
1645
1646<li>any other non-string input value will cause a type error.</li>
1647 </ul></li>
1648
1649<li>
1650<p>Example:</p>
1651
1652<div class="source">
1653<div class="source">
1654<pre>{ &quot;v1&quot;: initcap(&quot;ASTERIXDB is here!&quot;), &quot;v2&quot;: title(&quot;ASTERIXDB is here!&quot;) };
1655</pre></div></div></li>
1656</ul>
1657
1658<ul>
1659
1660<li>
1661<p>The expected result is:</p>
1662
1663<div class="source">
1664<div class="source">
1665<pre>{ &quot;v1&quot;: &quot;Asterixdb Is Here!&quot;, &quot;v2&quot;: &quot;Asterixdb Is Here!&quot; }
1666</pre></div></div></li>
1667</ul></div>
1668<div class="section">
1669<h3><a name="length"></a>length</h3>
1670
1671<ul>
1672
1673<li>
1674<p>Syntax:</p>
1675
1676<div class="source">
1677<div class="source">
1678<pre>length(string)
1679</pre></div></div></li>
1680
1681<li>
1682<p>Returns the length of the string <tt>string</tt>.</p></li>
1683
1684<li>Arguments:
1685
1686<ul>
1687
1688<li><tt>string</tt> : a <tt>string</tt> or <tt>null</tt> that represents the string to be checked.</li>
1689 </ul></li>
1690
1691<li>Return Value:
1692
1693<ul>
1694
1695<li>an <tt>bigint</tt> that represents the length of <tt>string</tt>,</li>
1696
1697<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
1698
1699<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
1700
1701<li>any other non-string input value will cause a type error.</li>
1702 </ul></li>
1703
1704<li>
1705<p>Example:</p>
1706
1707<div class="source">
1708<div class="source">
1709<pre>length(&quot;test string&quot;);
1710</pre></div></div></li>
1711</ul>
1712
1713<ul>
1714
1715<li>
1716<p>The expected result is:</p>
1717
1718<div class="source">
1719<div class="source">
1720<pre>11
1721</pre></div></div></li>
1722</ul></div>
1723<div class="section">
1724<h3><a name="lower"></a>lower</h3>
1725
1726<ul>
1727
1728<li>
1729<p>Syntax:</p>
1730
1731<div class="source">
1732<div class="source">
1733<pre>lower(string)
1734</pre></div></div></li>
1735
1736<li>
1737<p>Converts a given string <tt>string</tt> to its lowercase form.</p></li>
1738
1739<li>Arguments:
1740
1741<ul>
1742
1743<li><tt>string</tt> : a <tt>string</tt> to be converted.</li>
1744 </ul></li>
1745
1746<li>Return Value:
1747
1748<ul>
1749
1750<li>a <tt>string</tt> as the lowercase form of the given <tt>string</tt>,</li>
1751
1752<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
1753
1754<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
1755
1756<li>any other non-string input value will cause a type error.</li>
1757 </ul></li>
1758
1759<li>
1760<p>Example:</p>
1761
1762<div class="source">
1763<div class="source">
1764<pre>lower(&quot;ASTERIXDB&quot;);
1765</pre></div></div></li>
1766</ul>
1767
1768<ul>
1769
1770<li>
1771<p>The expected result is:</p>
1772
1773<div class="source">
1774<div class="source">
1775<pre>&quot;asterixdb&quot;
1776</pre></div></div></li>
1777</ul></div>
1778<div class="section">
1779<h3><a name="ltrim"></a>ltrim</h3>
1780
1781<ul>
1782
1783<li>
1784<p>Syntax:</p>
1785
1786<div class="source">
1787<div class="source">
1788<pre>ltrim(string[, chars]);
1789</pre></div></div></li>
1790
1791<li>
1792<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></li>
1793
1794<li>Arguments:
1795
1796<ul>
1797
1798<li><tt>string</tt> : a <tt>string</tt> to be trimmed,</li>
1799
1800<li><tt>chars</tt> : a <tt>string</tt> that contains characters that are used to trim.</li>
1801 </ul></li>
1802
1803<li>Return Value:
1804
1805<ul>
1806
1807<li>a trimmed, new <tt>string</tt>,</li>
1808
1809<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
1810
1811<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
1812
1813<li>any other non-string input value will cause a type error.</li>
1814 </ul></li>
1815</ul>
1816
1817<ul>
1818
1819<li>
1820<p>Example:</p>
1821
1822<div class="source">
1823<div class="source">
1824<pre>ltrim(&quot;me like x-phone&quot;, &quot;eml&quot;);
1825</pre></div></div></li>
1826</ul>
1827
1828<ul>
1829
1830<li>
1831<p>The expected result is:</p>
1832
1833<div class="source">
1834<div class="source">
1835<pre>&quot; like x-phone&quot;
1836</pre></div></div></li>
1837</ul></div>
1838<div class="section">
1839<h3><a name="position"></a>position</h3>
1840
1841<ul>
1842
1843<li>
1844<p>Syntax:</p>
1845
1846<div class="source">
1847<div class="source">
1848<pre>position(string, string_pattern)
1849</pre></div></div></li>
1850
1851<li>
1852<p>Returns the first position of <tt>string_pattern</tt> within <tt>string</tt>.</p></li>
1853
1854<li>Arguments:
1855
1856<ul>
1857
1858<li><tt>string</tt> : a <tt>string</tt> that might contain the pattern,</li>
1859
1860<li><tt>string_pattern</tt> : a pattern <tt>string</tt> to be matched.</li>
1861 </ul></li>
1862
1863<li>Return Value:
1864
1865<ul>
1866
1867<li>the first position that <tt>string_pattern</tt> appears within <tt>string</tt>, or -1 if it does not appear,</li>
1868
1869<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
1870
1871<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
1872
1873<li>any other non-string input value will cause a type error.</li>
1874 </ul></li>
1875
1876<li>
1877<p>Example:</p>
1878
1879<div class="source">
1880<div class="source">
1881<pre>{
1882 &quot;v1&quot;: position(&quot;ppphonepp&quot;, &quot;phone&quot;),
1883 &quot;v2&quot;: position(&quot;hone&quot;, &quot;phone&quot;)
1884};
1885</pre></div></div></li>
1886</ul>
1887
1888<ul>
1889
1890<li>
1891<p>The expected result is:</p>
1892
1893<div class="source">
1894<div class="source">
1895<pre>{ &quot;v1&quot;: 3, &quot;v2&quot;: -1 }
1896</pre></div></div></li>
1897</ul></div>
1898<div class="section">
1899<h3><a name="regexp_contains"></a>regexp_contains</h3>
1900
1901<ul>
1902
1903<li>
1904<p>Syntax:</p>
1905
1906<div class="source">
1907<div class="source">
1908<pre>regexp_contains(string, string_pattern[, string_flags])
1909</pre></div></div></li>
1910
1911<li>
1912<p>Checks whether the strings <tt>string</tt> contains the regular expression pattern <tt>string_pattern</tt> (a Java regular expression pattern).</p></li>
1913
1914<li>Arguments:
1915
1916<ul>
1917
1918<li><tt>string</tt> : a <tt>string</tt> that might contain the pattern,</li>
1919
1920<li><tt>string_pattern</tt> : a pattern <tt>string</tt> to be matched,</li>
1921
1922<li><tt>string_flag</tt> : (Optional) a <tt>string</tt> with flags to be used during regular expression matching.
1923
1924<ul>
1925
1926<li>The following modes are enabled with these flags: dotall (s), multiline (m), case_insensitive (i), and comments and whitespace (x).</li>
1927 </ul></li>
1928 </ul></li>
1929
1930<li>Return Value:
1931
1932<ul>
1933
1934<li>a <tt>boolean</tt>, returns <tt>true</tt> if <tt>string</tt> contains the pattern <tt>string_pattern</tt>,</li>
1935
1936<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
1937
1938<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
1939
1940<li>any other non-string input value will cause a type error,</li>
1941
1942<li><tt>false</tt> otherwise.</li>
1943 </ul></li>
1944
1945<li>
1946<p>Example:</p>
1947
1948<div class="source">
1949<div class="source">
1950<pre>{
1951 &quot;v1&quot;: regexp_contains(&quot;pphonepp&quot;, &quot;p*hone&quot;),
1952 &quot;v2&quot;: regexp_contains(&quot;hone&quot;, &quot;p+hone&quot;)
1953}
1954</pre></div></div></li>
1955</ul>
1956
1957<ul>
1958
1959<li>
1960<p>The expected result is:</p>
1961
1962<div class="source">
1963<div class="source">
1964<pre>{ &quot;v1&quot;: true, &quot;v2&quot;: false }
1965</pre></div></div></li>
1966</ul></div>
1967<div class="section">
1968<h3><a name="regexp_like"></a>regexp_like</h3>
1969
1970<ul>
1971
1972<li>
1973<p>Syntax:</p>
1974
1975<div class="source">
1976<div class="source">
1977<pre>regexp_like(string, string_pattern[, string_flags])
1978</pre></div></div></li>
1979
1980<li>
1981<p>Checks whether the string <tt>string</tt> exactly matches the regular expression pattern <tt>string_pattern</tt> (a Java regular expression pattern).</p></li>
1982
1983<li>Arguments:
1984
1985<ul>
1986
1987<li><tt>string</tt> : a <tt>string</tt> that might contain the pattern,</li>
1988
1989<li><tt>string_pattern</tt> : a pattern <tt>string</tt> that might be contained,</li>
1990
1991<li><tt>string_flag</tt> : (Optional) a <tt>string</tt> with flags to be used during regular expression matching.
1992
1993<ul>
1994
1995<li>The following modes are enabled with these flags: dotall (s), multiline (m), case_insensitive (i), and comments and whitespace (x).</li>
1996 </ul></li>
1997 </ul></li>
1998
1999<li>Return Value:
2000
2001<ul>
2002
2003<li>a <tt>boolean</tt> value, <tt>true</tt> if <tt>string</tt> contains the pattern <tt>string_pattern</tt>,</li>
2004
2005<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2006
2007<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2008
2009<li>any other non-string input value will cause a type error,</li>
2010
2011<li><tt>false</tt> otherwise.</li>
2012 </ul></li>
2013
2014<li>
2015<p>Example:</p>
2016
2017<div class="source">
2018<div class="source">
2019<pre>{
2020 &quot;v1&quot;: regexp_like(&quot; can't stand acast the network is horrible:(&quot;, &quot;.*acast.*&quot;),
2021 &quot;v2&quot;: regexp_like(&quot;acast&quot;, &quot;.*acst.*&quot;)
2022};
2023</pre></div></div></li>
2024
2025<li>
2026<p>The expected result is:</p>
2027
2028<div class="source">
2029<div class="source">
2030<pre>{ &quot;v1&quot;: true, &quot;v2&quot;: false }
2031</pre></div></div></li>
2032</ul></div>
2033<div class="section">
2034<h3><a name="regexp_position"></a>regexp_position</h3>
2035
2036<ul>
2037
2038<li>
2039<p>Syntax:</p>
2040
2041<div class="source">
2042<div class="source">
2043<pre>regexp_position(string, string_pattern[, string_flags])
2044</pre></div></div></li>
2045
2046<li>
2047<p>Returns first position of the regular expression <tt>string_pattern</tt> (a Java regular expression pattern) within <tt>string</tt>.</p></li>
2048
2049<li>Arguments:
2050
2051<ul>
2052
2053<li><tt>string</tt> : a <tt>string</tt> that might contain the pattern,</li>
2054
2055<li><tt>string_pattern</tt> : a pattern <tt>string</tt> to be matched,</li>
2056
2057<li><tt>string_flag</tt> : (Optional) a <tt>string</tt> with flags to be used during regular expression matching.
2058
2059<ul>
2060
2061<li>The following modes are enabled with these flags: dotall (s), multiline (m), case_insensitive (i), and comments and whitespace (x).</li>
2062 </ul></li>
2063 </ul></li>
2064
2065<li>Return Value:
2066
2067<ul>
2068
2069<li>the first position that the regular expression <tt>string_pattern</tt> appears in <tt>string</tt>, or -1 if it does not appear.</li>
2070
2071<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2072
2073<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2074
2075<li>any other non-string input value will cause a type error.</li>
2076 </ul></li>
2077
2078<li>
2079<p>Example:</p>
2080
2081<div class="source">
2082<div class="source">
2083<pre>{
2084 &quot;v1&quot;: regexp_position(&quot;pphonepp&quot;, &quot;p*hone&quot;),
2085 &quot;v2&quot;: regexp_position(&quot;hone&quot;, &quot;p+hone&quot;)
2086};
2087</pre></div></div></li>
2088</ul>
2089
2090<ul>
2091
2092<li>
2093<p>The expected result is:</p>
2094
2095<div class="source">
2096<div class="source">
2097<pre>{ &quot;v1&quot;: 1, &quot;v2&quot;: -1 }
2098</pre></div></div></li>
2099</ul></div>
2100<div class="section">
2101<h3><a name="regexp_replace"></a>regexp_replace</h3>
2102
2103<ul>
2104
2105<li>
2106<p>Syntax:</p>
2107
2108<div class="source">
2109<div class="source">
2110<pre>regexp_replace(string, string_pattern, string_replacement[, string_flags])
2111</pre></div></div></li>
2112
2113<li>
2114<p>Checks whether the string <tt>string</tt> matches the given regular expression pattern <tt>string_pattern</tt> (a Java regular expression pattern), and replace the matched pattern <tt>string_pattern</tt> with the new pattern <tt>string_replacement</tt>.</p></li>
2115
2116<li>Arguments:
2117
2118<ul>
2119
2120<li><tt>string</tt> : a <tt>string</tt> that might contain the pattern,</li>
2121
2122<li><tt>string_pattern</tt> : a pattern <tt>string</tt> to be matched,</li>
2123
2124<li><tt>string_replacement</tt> : a pattern <tt>string</tt> to be used as the replacement,</li>
2125
2126<li><tt>string_flag</tt> : (Optional) a <tt>string</tt> with flags to be used during replace.
2127
2128<ul>
2129
2130<li>The following modes are enabled with these flags: dotall (s), multiline (m), case_insensitive (i), and comments and whitespace (x).</li>
2131 </ul></li>
2132 </ul></li>
2133
2134<li>Return Value:
2135
2136<ul>
2137
2138<li>Returns a <tt>string</tt> that is obtained after the replacements,</li>
2139
2140<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2141
2142<li>any other non-string input value will cause a type error,</li>
2143
2144<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value.</li>
2145 </ul></li>
2146
2147<li>
2148<p>Example:</p>
2149
2150<div class="source">
2151<div class="source">
2152<pre>regexp_replace(&quot; like x-phone the voicemail_service is awesome&quot;, &quot; like x-phone&quot;, &quot;like product-a&quot;)
2153</pre></div></div></li>
2154</ul>
2155
2156<ul>
2157
2158<li>
2159<p>The expected result is:</p>
2160
2161<div class="source">
2162<div class="source">
2163<pre>&quot;like product-a the voicemail_service is awesome&quot;
2164</pre></div></div></li>
2165</ul></div>
2166<div class="section">
2167<h3><a name="repeat"></a>repeat</h3>
2168
2169<ul>
2170
2171<li>
2172<p>Syntax:</p>
2173
2174<div class="source">
2175<div class="source">
2176<pre>repeat(string, n)
2177</pre></div></div></li>
2178
2179<li>
2180<p>Returns a string formed by repeating the input <tt>string</tt> <tt>n</tt> times.</p></li>
2181
2182<li>Arguments:
2183
2184<ul>
2185
2186<li><tt>string</tt> : a <tt>string</tt> to be repeated,</li>
2187
2188<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>.</li>
2189 </ul></li>
2190
2191<li>Return Value:
2192
2193<ul>
2194
2195<li>a string that repeats the input <tt>string</tt> <tt>n</tt> times,</li>
2196
2197<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2198
2199<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2200
2201<li>a type error will be raised if:
2202
2203<ul>
2204
2205<li>the first argument is any other non-string value,</li>
2206
2207<li>or, the second argument is not a <tt>tinyint</tt>, <tt>smallint</tt>, <tt>integer</tt>, or <tt>bigint</tt>.</li>
2208 </ul></li>
2209 </ul></li>
2210
2211<li>
2212<p>Example:</p>
2213
2214<div class="source">
2215<div class="source">
2216<pre>repeat(&quot;test&quot;, 3);
2217</pre></div></div></li>
2218</ul>
2219
2220<ul>
2221
2222<li>
2223<p>The expected result is:</p>
2224
2225<div class="source">
2226<div class="source">
2227<pre>&quot;testtesttest&quot;
2228</pre></div></div></li>
2229</ul></div>
2230<div class="section">
2231<h3><a name="rtrim"></a>rtrim</h3>
2232
2233<ul>
2234
2235<li>
2236<p>Syntax:</p>
2237
2238<div class="source">
2239<div class="source">
2240<pre>rtrim(string[, chars]);
2241</pre></div></div></li>
2242
2243<li>
2244<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></li>
2245
2246<li>Arguments:
2247
2248<ul>
2249
2250<li><tt>string</tt> : a <tt>string</tt> to be trimmed,</li>
2251
2252<li><tt>chars</tt> : a <tt>string</tt> that contains characters that are used to trim.</li>
2253 </ul></li>
2254
2255<li>Return Value:
2256
2257<ul>
2258
2259<li>a trimmed, new <tt>string</tt>,</li>
2260
2261<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2262
2263<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2264
2265<li>any other non-string input value will cause a type error.</li>
2266 </ul></li>
2267</ul>
2268
2269<ul>
2270
2271<li>
2272<p>Example:</p>
2273
2274<div class="source">
2275<div class="source">
2276<pre>{
2277 &quot;v1&quot;: rtrim(&quot;i like x-phone&quot;, &quot;x-phone&quot;),
2278 &quot;v2&quot;: rtrim(&quot;i like x-phone&quot;, &quot;onexph&quot;)
2279};
2280</pre></div></div></li>
2281
2282<li>
2283<p>The expected result is:</p>
2284
2285<div class="source">
2286<div class="source">
2287<pre>{ &quot;v1&quot;: &quot;i like &quot;, &quot;v2&quot;: &quot;i like &quot; }
2288</pre></div></div></li>
2289</ul></div>
2290<div class="section">
2291<h3><a name="split"></a>split</h3>
2292
2293<ul>
2294
2295<li>
2296<p>Syntax:</p>
2297
2298<div class="source">
2299<div class="source">
2300<pre>split(string, sep)
2301</pre></div></div></li>
2302
2303<li>
2304<p>Splits the input <tt>string</tt> into an array of substrings separated by the string <tt>sep</tt>.</p></li>
2305
2306<li>Arguments:
2307
2308<ul>
2309
2310<li><tt>string</tt> : a <tt>string</tt> to be split.</li>
2311 </ul></li>
2312
2313<li>Return Value:
2314
2315<ul>
2316
2317<li>an array of substrings by splitting the input <tt>string</tt> by <tt>sep</tt>,</li>
2318
2319<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
2320
2321<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
2322
2323<li>any other non-string input value will cause a type error.</li>
2324 </ul></li>
2325
2326<li>
2327<p>Example:</p>
2328
2329<div class="source">
2330<div class="source">
2331<pre>split(&quot;test driven development&quot;, &quot; &quot;);
2332</pre></div></div></li>
2333</ul>
2334
2335<ul>
2336
2337<li>
2338<p>The expected result is:</p>
2339
2340<div class="source">
2341<div class="source">
2342<pre>[ &quot;test&quot;, &quot;driven&quot;, &quot;development&quot; ]
2343</pre></div></div></li>
2344</ul></div>
2345<div class="section">
2346<h3><a name="starts_with"></a>starts_with</h3>
2347
2348<ul>
2349
2350<li>
2351<p>Syntax:</p>
2352
2353<div class="source">
2354<div class="source">
2355<pre>starts_with(string, substring_to_start_with)
2356</pre></div></div></li>
2357
2358<li>
2359<p>Checks whether the string <tt>string</tt> starts with the string <tt>substring_to_start_with</tt>.</p></li>
2360
2361<li>Arguments:
2362
2363<ul>
2364
2365<li><tt>string</tt> : a <tt>string</tt> that might start with the given string.</li>
2366
2367<li><tt>substring_to_start_with</tt> : a <tt>string</tt> that might be contained as the starting substring.</li>
2368 </ul></li>
2369
2370<li>Return Value:
2371
2372<ul>
2373
2374<li>a <tt>boolean</tt>, returns <tt>true</tt> if <tt>string</tt> starts with the string <tt>substring_to_start_with</tt>,</li>
2375
2376<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2377
2378<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2379
2380<li>any other non-string input value will cause a type error,</li>
2381
2382<li><tt>false</tt> otherwise.</li>
2383 </ul></li>
2384
2385<li>
2386<p>Example:</p>
2387
2388<div class="source">
2389<div class="source">
2390<pre>{
2391 &quot;v1&quot; : starts_with(&quot; like the plan, amazing&quot;, &quot; like&quot;),
2392 &quot;v2&quot; : starts_with(&quot;I like the plan, amazing&quot;, &quot; like&quot;)
2393};
2394</pre></div></div></li>
2395</ul>
2396
2397<ul>
2398
2399<li>
2400<p>The expected result is:</p>
2401
2402<div class="source">
2403<div class="source">
2404<pre>{ &quot;v1&quot;: true, &quot;v2&quot;: false }
2405</pre></div></div></li>
2406</ul></div>
2407<div class="section">
2408<h3><a name="substr"></a>substr</h3>
2409
2410<ul>
2411
2412<li>
2413<p>Syntax:</p>
2414
2415<div class="source">
2416<div class="source">
2417<pre>substr(string, offset[, length])
2418</pre></div></div></li>
2419
2420<li>
2421<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></li>
2422
2423<li>Arguments:
2424
2425<ul>
2426
2427<li><tt>string</tt> : a <tt>string</tt> to be extracted,</li>
2428
2429<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>,</li>
2430
2431<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>
2432 </ul></li>
2433
2434<li>Return Value:
2435
2436<ul>
2437
2438<li>a <tt>string</tt> that represents the substring,</li>
2439
2440<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2441
2442<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2443
2444<li>a type error will be raised if:
2445
2446<ul>
2447
2448<li>the first argument is any other non-string value,</li>
2449
2450<li>or, the second argument is not a <tt>tinyint</tt>, <tt>smallint</tt>, <tt>integer</tt>, or <tt>bigint</tt>,</li>
2451
2452<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>
2453 </ul></li>
2454 </ul></li>
2455
2456<li>
2457<p>Example:</p>
2458
2459<div class="source">
2460<div class="source">
2461<pre>substr(&quot;test string&quot;, 6, 3);
2462</pre></div></div></li>
2463</ul>
2464
2465<ul>
2466
2467<li>
2468<p>The expected result is:</p>
2469
2470<div class="source">
2471<div class="source">
2472<pre>&quot;str&quot;
2473</pre></div></div></li>
2474</ul></div>
2475<div class="section">
2476<h3><a name="trim"></a>trim</h3>
2477
2478<ul>
2479
2480<li>
2481<p>Syntax:</p>
2482
2483<div class="source">
2484<div class="source">
2485<pre>trim(string[, chars]);
2486</pre></div></div></li>
2487
2488<li>
2489<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></li>
2490
2491<li>Arguments:
2492
2493<ul>
2494
2495<li><tt>string</tt> : a <tt>string</tt> to be trimmed,</li>
2496
2497<li><tt>chars</tt> : a <tt>string</tt> that contains characters that are used to trim.</li>
2498 </ul></li>
2499
2500<li>Return Value:
2501
2502<ul>
2503
2504<li>a trimmed, new <tt>string</tt>,</li>
2505
2506<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2507
2508<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2509
2510<li>any other non-string input value will cause a type error.</li>
2511 </ul></li>
2512</ul>
2513
2514<ul>
2515
2516<li>
2517<p>Example:</p>
2518
2519<div class="source">
2520<div class="source">
2521<pre>trim(&quot;i like x-phone&quot;, &quot;xphoen&quot;);
2522</pre></div></div></li>
2523</ul>
2524
2525<ul>
2526
2527<li>
2528<p>The expected result is:</p>
2529
2530<div class="source">
2531<div class="source">
2532<pre>&quot; like &quot;
2533</pre></div></div></li>
2534</ul></div>
2535<div class="section">
2536<h3><a name="upper"></a>upper</h3>
2537
2538<ul>
2539
2540<li>
2541<p>Syntax:</p>
2542
2543<div class="source">
2544<div class="source">
2545<pre>upper(string)
2546</pre></div></div></li>
2547
2548<li>
2549<p>Converts a given string <tt>string</tt> to its uppercase form.</p></li>
2550
2551<li>Arguments:
2552
2553<ul>
2554
2555<li><tt>string</tt> : a <tt>string</tt> to be converted.</li>
2556 </ul></li>
2557
2558<li>Return Value:
2559
2560<ul>
2561
2562<li>a <tt>string</tt> as the uppercase form of the given <tt>string</tt>,</li>
2563
2564<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
2565
2566<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
2567
2568<li>any other non-string input value will cause a type error.</li>
2569 </ul></li>
2570
2571<li>
2572<p>Example:</p>
2573
2574<div class="source">
2575<div class="source">
2576<pre>upper(&quot;hello&quot;)
2577</pre></div></div></li>
2578</ul>
2579
2580<ul>
2581
2582<li>
2583<p>The expected result is:</p>
2584
2585<div class="source">
2586<div class="source">
2587<pre>&quot;HELLO&quot;
2588</pre></div></div></li>
2589</ul>
2590<!-- ! Licensed to the Apache Software Foundation (ASF) under one
2591 ! or more contributor license agreements. See the NOTICE file
2592 ! distributed with this work for additional information
2593 ! regarding copyright ownership. The ASF licenses this file
2594 ! to you under the Apache License, Version 2.0 (the
2595 ! "License"); you may not use this file except in compliance
2596 ! with the License. You may obtain a copy of the License at
2597 !
2598 ! http://www.apache.org/licenses/LICENSE-2.0
2599 !
2600 ! Unless required by applicable law or agreed to in writing,
2601 ! software distributed under the License is distributed on an
2602 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
2603 ! KIND, either express or implied. See the License for the
2604 ! specific language governing permissions and limitations
2605 ! under the License.
2606 ! --></div>
2607<div class="section">
2608<h3><a name="string_concat"></a>string_concat</h3>
2609
2610<ul>
2611
2612<li>
2613<p>Syntax:</p>
2614
2615<div class="source">
2616<div class="source">
2617<pre>string_concat(array)
2618</pre></div></div></li>
2619
2620<li>
2621<p>Concatenates an array of strings <tt>array</tt> into a single string.</p></li>
2622
2623<li>Arguments:
2624
2625<ul>
2626
2627<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>
2628 </ul></li>
2629
2630<li>Return Value:
2631
2632<ul>
2633
2634<li>the concatenated <tt>string</tt> value,</li>
2635
2636<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
2637
2638<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2639
2640<li><tt>missing</tt> if any element in the input array is <tt>missing</tt>,</li>
2641
2642<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>
2643
2644<li>any other non-array input value or non-integer element in the input array will cause a type error.</li>
2645 </ul></li>
2646
2647<li>
2648<p>Example:</p>
2649
2650<div class="source">
2651<div class="source">
2652<pre>string_concat([&quot;ASTERIX&quot;, &quot; &quot;, &quot;ROCKS!&quot;]);
2653</pre></div></div></li>
2654</ul>
2655
2656<ul>
2657
2658<li>
2659<p>The expected result is:</p>
2660
2661<div class="source">
2662<div class="source">
2663<pre>&quot;ASTERIX ROCKS!&quot;
2664</pre></div></div></li>
2665</ul></div>
2666<div class="section">
2667<h3><a name="string_join"></a>string_join</h3>
2668
2669<ul>
2670
2671<li>
2672<p>Syntax:</p>
2673
2674<div class="source">
2675<div class="source">
2676<pre>string_join(array, string)
2677</pre></div></div></li>
2678
2679<li>
2680<p>Joins an array or multiset of strings <tt>array</tt> with the given separator <tt>string</tt> into a single string.</p></li>
2681
2682<li>Arguments:
2683
2684<ul>
2685
2686<li><tt>array</tt> : an <tt>array</tt> or <tt>multiset</tt> of strings (could be <tt>null</tt>) to be joined.</li>
2687
2688<li><tt>string</tt> : a <tt>string</tt> to serve as the separator.</li>
2689 </ul></li>
2690
2691<li>Return Value:
2692
2693<ul>
2694
2695<li>the joined <tt>string</tt>,</li>
2696
2697<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2698
2699<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2700
2701<li><tt>missing</tt> if the first argument array contains a <tt>missing</tt>,</li>
2702
2703<li><tt>null</tt> if the first argument array contains a <tt>null</tt> but does not contain a <tt>missing</tt>,</li>
2704
2705<li>a type error will be raised if:
2706
2707<ul>
2708
2709<li>the first argument is any other non-array value, or contains any other non-string value,</li>
2710
2711<li>or, the second argument is any other non-string value.</li>
2712 </ul></li>
2713 </ul></li>
2714
2715<li>
2716<p>Example:</p>
2717
2718<div class="source">
2719<div class="source">
2720<pre>string_join([&quot;ASTERIX&quot;, &quot;ROCKS~&quot;], &quot;!! &quot;);
2721</pre></div></div></li>
2722</ul>
2723
2724<ul>
2725
2726<li>
2727<p>The expected result is:</p>
2728
2729<div class="source">
2730<div class="source">
2731<pre>&quot;ASTERIX!! ROCKS~&quot;
2732</pre></div></div></li>
2733</ul></div>
2734<div class="section">
2735<h3><a name="string_to_codepoint"></a>string_to_codepoint</h3>
2736
2737<ul>
2738
2739<li>
2740<p>Syntax:</p>
2741
2742<div class="source">
2743<div class="source">
2744<pre>string_to_codepoint(string)
2745</pre></div></div></li>
2746
2747<li>
2748<p>Converts the string <tt>string</tt> to its code_based representation.</p></li>
2749
2750<li>Arguments:
2751
2752<ul>
2753
2754<li><tt>string</tt> : a <tt>string</tt> that will be converted.</li>
2755 </ul></li>
2756
2757<li>Return Value:
2758
2759<ul>
2760
2761<li>an <tt>array</tt> of the code points for the string <tt>string</tt>,</li>
2762
2763<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
2764
2765<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
2766
2767<li>any other non-string input value will cause a type error.</li>
2768 </ul></li>
2769
2770<li>
2771<p>Example:</p>
2772
2773<div class="source">
2774<div class="source">
2775<pre>string_to_codepoint(&quot;Hello ASTERIX!&quot;);
2776</pre></div></div></li>
2777</ul>
2778
2779<ul>
2780
2781<li>
2782<p>The expected result is:</p>
2783
2784<div class="source">
2785<div class="source">
2786<pre>[ 72, 101, 108, 108, 111, 32, 65, 83, 84, 69, 82, 73, 88, 33 ]
2787</pre></div></div></li>
2788</ul></div>
2789<div class="section">
2790<h3><a name="codepoint_to_string"></a>codepoint_to_string</h3>
2791
2792<ul>
2793
2794<li>
2795<p>Syntax:</p>
2796
2797<div class="source">
2798<div class="source">
2799<pre>codepoint_to_string(array)
2800</pre></div></div></li>
2801
2802<li>
2803<p>Converts the ordered code_based representation <tt>array</tt> to the corresponding string.</p></li>
2804
2805<li>Arguments:
2806
2807<ul>
2808
2809<li><tt>array</tt> : an <tt>array</tt> of integer code_points.</li>
2810 </ul></li>
2811
2812<li>Return Value:
2813
2814<ul>
2815
2816<li>a <tt>string</tt> representation of <tt>array</tt>.</li>
2817
2818<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
2819
2820<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
2821
2822<li><tt>missing</tt> if any element in the input array is <tt>missing</tt>,</li>
2823
2824<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>
2825
2826<li>any other non-array input value or non-integer element in the input array will cause a type error.</li>
2827 </ul></li>
2828
2829<li>
2830<p>Example:</p>
2831
2832<div class="source">
2833<div class="source">
2834<pre>codepoint_to_string([72, 101, 108, 108, 111, 32, 65, 83, 84, 69, 82, 73, 88, 33]);
2835</pre></div></div></li>
2836</ul>
2837
2838<ul>
2839
2840<li>
2841<p>The expected result is:</p>
2842
2843<div class="source">
2844<div class="source">
2845<pre>&quot;Hello ASTERIX!&quot;
2846</pre></div></div></li>
2847</ul></div>
2848<div class="section">
2849<h3><a name="substring_before"></a>substring_before</h3>
2850
2851<ul>
2852
2853<li>
2854<p>Syntax:</p>
2855
2856<div class="source">
2857<div class="source">
2858<pre>substring_before(string, string_pattern)
2859</pre></div></div></li>
2860
2861<li>
2862<p>Returns the substring from the given string <tt>string</tt> before the given pattern <tt>string_pattern</tt>.</p></li>
2863
2864<li>Arguments:
2865
2866<ul>
2867
2868<li><tt>string</tt> : a <tt>string</tt> to be extracted.</li>
2869
2870<li><tt>string_pattern</tt> : a <tt>string</tt> pattern to be searched.</li>
2871 </ul></li>
2872
2873<li>Return Value:
2874
2875<ul>
2876
2877<li>a <tt>string</tt> that represents the substring,</li>
2878
2879<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2880
2881<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2882
2883<li>any other non-string input value will cause a type error.</li>
2884 </ul></li>
2885
2886<li>
2887<p>Example:</p>
2888
2889<div class="source">
2890<div class="source">
2891<pre>substring_before(&quot; like x-phone&quot;, &quot;x-phone&quot;);
2892</pre></div></div></li>
2893</ul>
2894
2895<ul>
2896
2897<li>
2898<p>The expected result is:</p>
2899
2900<div class="source">
2901<div class="source">
2902<pre>&quot; like &quot;
2903</pre></div></div></li>
2904</ul></div>
2905<div class="section">
2906<h3><a name="substring_after"></a>substring_after</h3>
2907
2908<ul>
2909
2910<li>
2911<p>Syntax:</p>
2912<p>substring_after(string, string_pattern);</p></li>
2913
2914<li>
2915<p>Returns the substring from the given string <tt>string</tt> after the given pattern <tt>string_pattern</tt>.</p></li>
2916
2917<li>Arguments:
2918
2919<ul>
2920
2921<li><tt>string</tt> : a <tt>string</tt> to be extracted.</li>
2922
2923<li><tt>string_pattern</tt> : a <tt>string</tt> pattern to be searched.</li>
2924 </ul></li>
2925
2926<li>Return Value:
2927
2928<ul>
2929
2930<li>a <tt>string</tt> that represents the substring,</li>
2931
2932<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2933
2934<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2935
2936<li>any other non-string input value will cause a type error.</li>
2937 </ul></li>
2938</ul>
2939
2940<ul>
2941
2942<li>
2943<p>Example:</p>
2944
2945<div class="source">
2946<div class="source">
2947<pre>substring_after(&quot; like x-phone&quot;, &quot;xph&quot;);
2948</pre></div></div></li>
2949</ul>
2950
2951<ul>
2952
2953<li>
2954<p>The expected result is:</p>
2955
2956<div class="source">
2957<div class="source">
2958<pre>&quot;one&quot;
2959</pre></div></div></li>
2960</ul>
2961<!-- ! Licensed to the Apache Software Foundation (ASF) under one
2962 ! or more contributor license agreements. See the NOTICE file
2963 ! distributed with this work for additional information
2964 ! regarding copyright ownership. The ASF licenses this file
2965 ! to you under the Apache License, Version 2.0 (the
2966 ! "License"); you may not use this file except in compliance
2967 ! with the License. You may obtain a copy of the License at
2968 !
2969 ! http://www.apache.org/licenses/LICENSE-2.0
2970 !
2971 ! Unless required by applicable law or agreed to in writing,
2972 ! software distributed under the License is distributed on an
2973 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
2974 ! KIND, either express or implied. See the License for the
2975 ! specific language governing permissions and limitations
2976 ! under the License.
2977 ! --></div></div>
2978<div class="section">
2979<h2><a name="Binary_Functions"></a><a name="BinaryFunctions" id="BinaryFunctions">Binary Functions</a></h2>
2980<div class="section">
2981<h3><a name="parse_binary"></a>parse_binary</h3>
2982
2983<ul>
2984
2985<li>
2986<p>Syntax:</p>
2987<p>parse_binary(string, encoding)</p></li>
2988
2989<li>
2990<p>Creates a <tt>binary</tt> from an string encoded in <tt>encoding</tt> format.</p></li>
2991
2992<li>Arguments:
2993
2994<ul>
2995
2996<li><tt>string</tt> : an encoded <tt>string</tt>,</li>
2997
2998<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>
2999 </ul></li>
3000
3001<li>Return Value:
3002
3003<ul>
3004
3005<li>a <tt>binary</tt> that is decoded from the given <tt>string</tt>,</li>
3006
3007<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3008
3009<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3010
3011<li>any other non-string input value will cause a type error.</li>
3012 </ul></li>
3013
3014<li>
3015<p>Example:</p>
3016<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></li>
3017
3018<li>
3019<p>The expected result is:</p>
3020<p>[ hex(&#x201c;ABCDEF0123456789&#x201d;), hex(&#x201c;ABCDEF0123456789&#x201d;), hex(&#x201c;4173746572697801&#x201d;) ]</p></li>
3021</ul></div>
3022<div class="section">
3023<h3><a name="print_binary"></a>print_binary</h3>
3024
3025<ul>
3026
3027<li>
3028<p>Syntax:</p>
3029<p>print_binary(binary, encoding)</p></li>
3030
3031<li>
3032<p>Prints a <tt>binary</tt> to the required encoding <tt>string</tt> format.</p></li>
3033
3034<li>Arguments:
3035
3036<ul>
3037
3038<li><tt>binary</tt> : a <tt>binary</tt> data need to be printed.</li>
3039
3040<li><tt>encoding</tt> : a string notation specifies the expected encoding type. Currently we support <tt>hex</tt> and <tt>base64</tt> format.</li>
3041 </ul></li>
3042
3043<li>Return Value:
3044
3045<ul>
3046
3047<li>a <tt>string</tt> that represents the encoded format of a <tt>binary</tt>,</li>
3048
3049<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3050
3051<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3052
3053<li>any other non-string input value will cause a type error.</li>
3054 </ul></li>
3055
3056<li>
3057<p>Example:</p>
3058
3059<div class="source">
3060<div class="source">
3061<pre>[ print_binary(hex(&quot;ABCDEF0123456789&quot;), &quot;base64&quot;), print_binary(base64(&quot;q83vASNFZ4k=&quot;), &quot;hex&quot;) ]
3062</pre></div></div></li>
3063
3064<li>
3065<p>The expected result are:</p>
3066
3067<div class="source">
3068<div class="source">
3069<pre>[ &quot;q83vASNFZ4k=&quot;, &quot;ABCDEF0123456789&quot; ]
3070</pre></div></div></li>
3071</ul></div>
3072<div class="section">
3073<h3><a name="binary_length"></a>binary_length</h3>
3074
3075<ul>
3076
3077<li>
3078<p>Syntax:</p>
3079<p>binary_length(binary)</p></li>
3080
3081<li>
3082<p>Returns the number of bytes storing the binary data.</p></li>
3083
3084<li>Arguments:
3085
3086<ul>
3087
3088<li><tt>binary</tt> : a <tt>binary</tt> value to be checked.</li>
3089 </ul></li>
3090
3091<li>Return Value:
3092
3093<ul>
3094
3095<li>an <tt>bigint</tt> that represents the number of bytes,</li>
3096
3097<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
3098
3099<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
3100
3101<li>any other non-binary input value will cause a type error.</li>
3102 </ul></li>
3103
3104<li>
3105<p>Example:</p>
3106
3107<div class="source">
3108<div class="source">
3109<pre>binary_length(hex(&quot;00AA&quot;))
3110</pre></div></div></li>
3111
3112<li>
3113<p>The expected result is:</p>
3114<p>2</p></li>
3115</ul></div>
3116<div class="section">
3117<h3><a name="sub_binary"></a>sub_binary</h3>
3118
3119<ul>
3120
3121<li>
3122<p>Syntax:</p>
3123<p>sub_binary(binary, offset[, length])</p></li>
3124
3125<li>
3126<p>Returns the sub binary from the given <tt>binary</tt> based on the given start offset with the optional <tt>length</tt>.</p></li>
3127
3128<li>Arguments:
3129
3130<ul>
3131
3132<li><tt>binary</tt> : a <tt>binary</tt> to be extracted,</li>
3133
3134<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>,</li>
3135
3136<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>
3137 </ul></li>
3138
3139<li>Return Value:
3140
3141<ul>
3142
3143<li>a <tt>binary</tt> that represents the sub binary,</li>
3144
3145<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3146
3147<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3148
3149<li>a type error will be raised if:
3150
3151<ul>
3152
3153<li>the first argument is any other non-binary value,</li>
3154
3155<li>or, the second argument is any other non-integer value,</li>
3156
3157<li>or, the third argument is any other non-integer value, if it is present.</li>
3158 </ul></li>
3159 </ul></li>
3160
3161<li>
3162<p>Example:</p>
3163
3164<div class="source">
3165<div class="source">
3166<pre>sub_binary(hex(&quot;AABBCCDD&quot;), 4);
3167</pre></div></div></li>
3168
3169<li>
3170<p>The expected result is</p>
3171
3172<div class="source">
3173<div class="source">
3174<pre>hex(&quot;DD&quot;)
3175</pre></div></div></li>
3176</ul></div>
3177<div class="section">
3178<h3><a name="binary_concat"></a>binary_concat</h3>
3179
3180<ul>
3181
3182<li>
3183<p>Syntax:</p>
3184<p>binary_concat(array)</p></li>
3185
3186<li>
3187<p>Concatenates a binary <tt>array</tt> or <tt>multiset</tt> into a single binary.</p></li>
3188
3189<li>Arguments:
3190
3191<ul>
3192
3193<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>
3194 </ul></li>
3195
3196<li>Return Value :
3197
3198<ul>
3199
3200<li>the concatenated <tt>binary</tt> value,</li>
3201
3202<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
3203
3204<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
3205
3206<li><tt>missing</tt> if any element in the input array is <tt>missing</tt>,</li>
3207
3208<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>
3209
3210<li>any other non-array input value or non-binary element in the input array will cause a type error.</li>
3211 </ul></li>
3212
3213<li>
3214<p>Example:</p>
3215<p>binary_concat([hex(&#x201c;42&#x201d;), hex(&quot;&quot;), hex(&#x2018;42&#x2019;)]);</p></li>
3216
3217<li>
3218<p>The expected result is</p>
3219<p>hex(&#x201c;4242&#x201d;)</p></li>
3220</ul>
3221<!-- ! Licensed to the Apache Software Foundation (ASF) under one
3222 ! or more contributor license agreements. See the NOTICE file
3223 ! distributed with this work for additional information
3224 ! regarding copyright ownership. The ASF licenses this file
3225 ! to you under the Apache License, Version 2.0 (the
3226 ! "License"); you may not use this file except in compliance
3227 ! with the License. You may obtain a copy of the License at
3228 !
3229 ! http://www.apache.org/licenses/LICENSE-2.0
3230 !
3231 ! Unless required by applicable law or agreed to in writing,
3232 ! software distributed under the License is distributed on an
3233 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
3234 ! KIND, either express or implied. See the License for the
3235 ! specific language governing permissions and limitations
3236 ! under the License.
3237 ! --></div></div>
3238<div class="section">
3239<h2><a name="Spatial_Functions"></a><a name="SpatialFunctions" id="SpatialFunctions">Spatial Functions</a></h2>
3240<div class="section">
3241<h3><a name="create_point"></a>create_point</h3>
3242
3243<ul>
3244
3245<li>
3246<p>Syntax:</p>
3247
3248<div class="source">
3249<div class="source">
3250<pre>create_point(x, y)
3251</pre></div></div></li>
3252
3253<li>
3254<p>Creates the primitive type <tt>point</tt> using an <tt>x</tt> and <tt>y</tt> value.</p></li>
3255
3256<li>Arguments:</li>
3257
3258<li><tt>x</tt> : a <tt>double</tt> that represents the x-coordinate,</li>
3259
3260<li><tt>y</tt> : a <tt>double</tt> that represents the y-coordinate.</li>
3261
3262<li>Return Value:</li>
3263
3264<li>a <tt>point</tt> representing the ordered pair (<tt>x</tt>, <tt>y</tt>),</li>
3265
3266<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3267
3268<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3269
3270<li>any other non-double input value will cause a type error.</li>
3271
3272<li>
3273<p>Example:</p>
3274
3275<div class="source">
3276<div class="source">
3277<pre>{ &quot;point&quot;: create_point(30.0,70.0) };
3278</pre></div></div></li>
3279</ul>
3280
3281<ul>
3282
3283<li>
3284<p>The expected result is:</p>
3285
3286<div class="source">
3287<div class="source">
3288<pre>{ &quot;point&quot;: point(&quot;30.0,70.0&quot;) }
3289</pre></div></div></li>
3290</ul></div>
3291<div class="section">
3292<h3><a name="create_line"></a>create_line</h3>
3293
3294<ul>
3295
3296<li>
3297<p>Syntax:</p>
3298
3299<div class="source">
3300<div class="source">
3301<pre>create_line(point1, point2)
3302</pre></div></div></li>
3303
3304<li>
3305<p>Creates the primitive type <tt>line</tt> using <tt>point1</tt> and <tt>point2</tt>.</p></li>
3306
3307<li>Arguments:
3308
3309<ul>
3310
3311<li><tt>point1</tt> : a <tt>point</tt> that represents the start point of the line.</li>
3312
3313<li><tt>point2</tt> : a <tt>point</tt> that represents the end point of the line.</li>
3314 </ul></li>
3315
3316<li>Return Value:
3317
3318<ul>
3319
3320<li>a spatial <tt>line</tt> created using the points provided in <tt>point1</tt> and <tt>point2</tt>,</li>
3321
3322<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3323
3324<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3325
3326<li>any other non-point input value will cause a type error.</li>
3327 </ul></li>
3328
3329<li>
3330<p>Example:</p>
3331
3332<div class="source">
3333<div class="source">
3334<pre>{ &quot;line&quot;: create_line(create_point(30.0,70.0), create_point(50.0,90.0)) };
3335</pre></div></div></li>
3336</ul>
3337
3338<ul>
3339
3340<li>
3341<p>The expected result is:</p>
3342
3343<div class="source">
3344<div class="source">
3345<pre>{ &quot;line&quot;: line(&quot;30.0,70.0 50.0,90.0&quot;) }
3346</pre></div></div></li>
3347</ul></div>
3348<div class="section">
3349<h3><a name="create_rectangle"></a>create_rectangle</h3>
3350
3351<ul>
3352
3353<li>
3354<p>Syntax:</p>
3355
3356<div class="source">
3357<div class="source">
3358<pre>create_rectangle(point1, point2)
3359</pre></div></div></li>
3360
3361<li>
3362<p>Creates the primitive type <tt>rectangle</tt> using <tt>point1</tt> and <tt>point2</tt>.</p></li>
3363
3364<li>Arguments:
3365
3366<ul>
3367
3368<li><tt>point1</tt> : a <tt>point</tt> that represents the lower_left point of the rectangle.</li>
3369
3370<li><tt>point2</tt> : a <tt>point</tt> that represents the upper_right point of the rectangle.</li>
3371 </ul></li>
3372
3373<li>Return Value:
3374
3375<ul>
3376
3377<li>a spatial <tt>rectangle</tt> created using the points provided in <tt>point1</tt> and <tt>point2</tt>,</li>
3378
3379<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3380
3381<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3382
3383<li>any other non-point input value will cause a type error.</li>
3384 </ul></li>
3385
3386<li>
3387<p>Example:</p>
3388
3389<div class="source">
3390<div class="source">
3391<pre>{ &quot;rectangle&quot;: create_rectangle(create_point(30.0,70.0), create_point(50.0,90.0)) };
3392</pre></div></div></li>
3393</ul>
3394
3395<ul>
3396
3397<li>
3398<p>The expected result is:</p>
3399
3400<div class="source">
3401<div class="source">
3402<pre>{ &quot;rectangle&quot;: rectangle(&quot;30.0,70.0 50.0,90.0&quot;) }
3403</pre></div></div></li>
3404</ul></div>
3405<div class="section">
3406<h3><a name="create_circle"></a>create_circle</h3>
3407
3408<ul>
3409
3410<li>
3411<p>Syntax:</p>
3412
3413<div class="source">
3414<div class="source">
3415<pre>create_circle(point, radius)
3416</pre></div></div></li>
3417
3418<li>
3419<p>Creates the primitive type <tt>circle</tt> using <tt>point</tt> and <tt>radius</tt>.</p></li>
3420
3421<li>Arguments:
3422
3423<ul>
3424
3425<li><tt>point</tt> : a <tt>point</tt> that represents the center of the circle.</li>
3426
3427<li><tt>radius</tt> : a <tt>double</tt> that represents the radius of the circle.</li>
3428 </ul></li>
3429
3430<li>Return Value:
3431
3432<ul>
3433
3434<li>a spatial <tt>circle</tt> created using the center point and the radius provided in <tt>point</tt> and <tt>radius</tt>.</li>
3435
3436<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3437
3438<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3439
3440<li>a type error will be raised if:
3441
3442<ul>
3443
3444<li>the first argument is any other non-point value,</li>
3445
3446<li>or, the second argument is any other non-double value.</li>
3447 </ul></li>
3448 </ul></li>
3449
3450<li>
3451<p>Example:</p>
3452
3453<div class="source">
3454<div class="source">
3455<pre>{ &quot;circle&quot;: create_circle(create_point(30.0,70.0), 5.0) }
3456</pre></div></div></li>
3457</ul>
3458
3459<ul>
3460
3461<li>
3462<p>The expected result is:</p>
3463
3464<div class="source">
3465<div class="source">
3466<pre>{ &quot;circle&quot;: circle(&quot;30.0,70.0 5.0&quot;) }
3467</pre></div></div></li>
3468</ul></div>
3469<div class="section">
3470<h3><a name="create_polygon"></a>create_polygon</h3>
3471
3472<ul>
3473
3474<li>
3475<p>Syntax:</p>
3476
3477<div class="source">
3478<div class="source">
3479<pre>create_polygon(array)
3480</pre></div></div></li>
3481
3482<li>
3483<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></li>
3484
3485<li>Arguments:
3486
3487<ul>
3488
3489<li><tt>array</tt> : an array of doubles representing the points of the polygon.</li>
3490 </ul></li>
3491
3492<li>Return Value:
3493
3494<ul>
3495
3496<li>a <tt>polygon</tt>, represents a spatial simple polygon created using the points provided in <tt>array</tt>.</li>
3497
3498<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
3499
3500<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
3501
3502<li><tt>missing</tt> if any element in the input array is <tt>missing</tt>,</li>
3503
3504<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>
3505
3506<li>any other non-array input value or non-double element in the input array will cause a type error.</li>
3507 </ul></li>
3508</ul>
3509
3510<ul>
3511
3512<li>
3513<p>Example:</p>
3514
3515<div class="source">
3516<div class="source">
3517<pre>{ &quot;polygon&quot;: create_polygon([1.0,1.0,2.0,2.0,3.0,3.0,4.0,4.0]) };
3518</pre></div></div></li>
3519</ul>
3520
3521<ul>
3522
3523<li>
3524<p>The expected result is:</p>
3525
3526<div class="source">
3527<div class="source">
3528<pre>{ &quot;polygon&quot;: polygon(&quot;1.0,1.0 2.0,2.0 3.0,3.0 4.0,4.0&quot;) }
3529</pre></div></div></li>
3530</ul></div>
3531<div class="section">
3532<h3><a name="get_xget_y"></a>get_x/get_y</h3>
3533
3534<ul>
3535
3536<li>
3537<p>Syntax:</p>
3538
3539<div class="source">
3540<div class="source">
3541<pre>get_x(point) or get_y(point)
3542</pre></div></div></li>
3543
3544<li>
3545<p>Returns the x or y coordinates of a point <tt>point</tt>.</p></li>
3546
3547<li>Arguments:
3548
3549<ul>
3550
3551<li><tt>point</tt> : a <tt>point</tt>.</li>
3552 </ul></li>
3553
3554<li>Return Value:
3555
3556<ul>
3557
3558<li>a <tt>double</tt> representing the x or y coordinates of the point <tt>point</tt>,</li>
3559
3560<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
3561
3562<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
3563
3564<li>any other non-point input value will cause a type error.</li>
3565 </ul></li>
3566
3567<li>
3568<p>Example:</p>
3569
3570<div class="source">
3571<div class="source">
3572<pre>{ &quot;x_coordinate&quot;: get_x(create_point(2.3,5.0)), &quot;y_coordinate&quot;: get_y(create_point(2.3,5.0)) };
3573</pre></div></div></li>
3574</ul>
3575
3576<ul>
3577
3578<li>
3579<p>The expected result is:</p>
3580
3581<div class="source">
3582<div class="source">
3583<pre>{ &quot;x_coordinate&quot;: 2.3, &quot;y_coordinate&quot;: 5.0 }
3584</pre></div></div></li>
3585</ul></div>
3586<div class="section">
3587<h3><a name="get_points"></a>get_points</h3>
3588
3589<ul>
3590
3591<li>
3592<p>Syntax:</p>
3593
3594<div class="source">
3595<div class="source">
3596<pre>get_points(spatial_object)
3597</pre></div></div></li>
3598
3599<li>
3600<p>Returns an ordered array of the points forming the spatial object <tt>spatial_object</tt>.</p></li>
3601
3602<li>Arguments:
3603
3604<ul>
3605
3606<li><tt>spatial_object</tt> : a <tt>point</tt>, <tt>line</tt>, <tt>rectangle</tt>, <tt>circle</tt>, or <tt>polygon</tt>.</li>
3607 </ul></li>
3608
3609<li>Return Value:
3610
3611<ul>
3612
3613<li>an <tt>array</tt> of the points forming the spatial object <tt>spatial_object</tt>,</li>
3614
3615<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
3616
3617<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
3618
3619<li>any other non-spatial-object input value will cause a type error.</li>
3620 </ul></li>
3621
3622<li>
3623<p>Example:</p>
3624
3625<div class="source">
3626<div class="source">
3627<pre>get_points(create_polygon([1.0,1.0,2.0,2.0,3.0,3.0,4.0,4.0]))
3628</pre></div></div></li>
3629
3630<li>
3631<p>The expected result is:</p>
3632
3633<div class="source">
3634<div class="source">
3635<pre>[ 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;) ]
3636</pre></div></div></li>
3637</ul></div>
3638<div class="section">
3639<h3><a name="get_centerget_radius"></a>get_center/get_radius</h3>
3640
3641<ul>
3642
3643<li>
3644<p>Syntax:</p>
3645
3646<div class="source">
3647<div class="source">
3648<pre>get_center(circle_expression) or get_radius(circle_expression)
3649</pre></div></div></li>
3650
3651<li>
3652<p>Returns the center and the radius of a circle <tt>circle_expression</tt>, respectively.</p></li>
3653
3654<li>Arguments:
3655
3656<ul>
3657
3658<li><tt>circle_expression</tt> : a <tt>circle</tt>.</li>
3659 </ul></li>
3660
3661<li>Return Value:
3662
3663<ul>
3664
3665<li>a <tt>point</tt> or <tt>double</tt>, represent the center or radius of the circle <tt>circle_expression</tt>.</li>
3666
3667<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
3668
3669<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
3670
3671<li>any other non-circle input value will cause a type error.</li>
3672 </ul></li>
3673
3674<li>
3675<p>Example:</p>
3676
3677<div class="source">
3678<div class="source">
3679<pre>{
3680 &quot;circle_radius&quot;: get_radius(create_circle(create_point(6.0,3.0), 1.0)),
3681 &quot;circle_center&quot;: get_center(create_circle(create_point(6.0,3.0), 1.0))
3682};
3683</pre></div></div></li>
3684</ul>
3685
3686<ul>
3687
3688<li>
3689<p>The expected result is:</p>
3690
3691<div class="source">
3692<div class="source">
3693<pre>{ &quot;circle_radius&quot;: 1.0, &quot;circle_center&quot;: point(&quot;6.0,3.0&quot;) }
3694</pre></div></div></li>
3695</ul></div>
3696<div class="section">
3697<h3><a name="spatial_distance"></a>spatial_distance</h3>
3698
3699<ul>
3700
3701<li>
3702<p>Syntax:</p>
3703
3704<div class="source">
3705<div class="source">
3706<pre>spatial_distance(point1, point2)
3707</pre></div></div></li>
3708
3709<li>
3710<p>Returns the Euclidean distance between <tt>point1</tt> and <tt>point2</tt>.</p></li>
3711
3712<li>Arguments:
3713
3714<ul>
3715
3716<li><tt>point1</tt> : a <tt>point</tt>.</li>
3717
3718<li><tt>point2</tt> : a <tt>point</tt>.</li>
3719 </ul></li>
3720
3721<li>Return Value:
3722
3723<ul>
3724
3725<li>a <tt>double</tt> as the Euclidean distance between <tt>point1</tt> and <tt>point2</tt>.</li>
3726
3727<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3728
3729<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3730
3731<li>any other non-point input value will cause a type error.</li>
3732 </ul></li>
3733
3734<li>
3735<p>Example:</p>
3736
3737<div class="source">
3738<div class="source">
3739<pre>spatial_distance(point(&quot;47.44,80.65&quot;), create_point(30.0,70.0));
3740</pre></div></div></li>
3741</ul>
3742
3743<ul>
3744
3745<li>
3746<p>The expected result is:</p>
3747
3748<div class="source">
3749<div class="source">
3750<pre>20.434678857275934
3751</pre></div></div></li>
3752</ul></div>
3753<div class="section">
3754<h3><a name="spatial_area"></a>spatial_area</h3>
3755
3756<ul>
3757
3758<li>
3759<p>Syntax:</p>
3760
3761<div class="source">
3762<div class="source">
3763<pre>spatial_area(spatial_2d_expression)
3764</pre></div></div></li>
3765
3766<li>
3767<p>Returns the spatial area of <tt>spatial_2d_expression</tt>.</p></li>
3768
3769<li>Arguments:
3770
3771<ul>
3772
3773<li><tt>spatial_2d_expression</tt> : a <tt>rectangle</tt>, <tt>circle</tt>, or <tt>polygon</tt>.</li>
3774 </ul></li>
3775
3776<li>Return Value:
3777
3778<ul>
3779
3780<li>a <tt>double</tt> representing the area of <tt>spatial_2d_expression</tt>.</li>
3781
3782<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
3783
3784<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
3785
3786<li>any other non-2d-spatial-object will cause a type error.</li>
3787 </ul></li>
3788
3789<li>
3790<p>Example:</p>
3791
3792<div class="source">
3793<div class="source">
3794<pre>spatial_area(create_circle(create_point(0.0,0.0), 5.0));
3795</pre></div></div></li>
3796</ul>
3797
3798<ul>
3799
3800<li>
3801<p>The expected result is:</p>
3802
3803<div class="source">
3804<div class="source">
3805<pre>78.53981625
3806</pre></div></div></li>
3807</ul></div>
3808<div class="section">
3809<h3><a name="spatial_intersect"></a>spatial_intersect</h3>
3810
3811<ul>
3812
3813<li>
3814<p>Syntax:</p>
3815
3816<div class="source">
3817<div class="source">
3818<pre>spatial_intersect(spatial_object1, spatial_object2)
3819</pre></div></div></li>
3820
3821<li>
3822<p>Checks whether <tt>@arg1</tt> and <tt>@arg2</tt> spatially intersect each other.</p></li>
3823
3824<li>Arguments:
3825
3826<ul>
3827
3828<li><tt>spatial_object1</tt> : a <tt>point</tt>, <tt>line</tt>, <tt>rectangle</tt>, <tt>circle</tt>, or <tt>polygon</tt>.</li>
3829
3830<li><tt>spatial_object2</tt> : a <tt>point</tt>, <tt>line</tt>, <tt>rectangle</tt>, <tt>circle</tt>, or <tt>polygon</tt>.</li>
3831 </ul></li>
3832
3833<li>Return Value:
3834
3835<ul>
3836
3837<li>a <tt>boolean</tt> representing whether <tt>spatial_object1</tt> and <tt>spatial_object2</tt> spatially overlap with each other,</li>
3838
3839<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3840
3841<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3842
3843<li>any other non-spatial-object input value will cause a type error.</li>
3844 </ul></li>
3845
3846<li>
3847<p>Example:</p>
3848
3849<div class="source">
3850<div class="source">
3851<pre>spatial_intersect(point(&quot;39.28,70.48&quot;), create_rectangle(create_point(30.0,70.0), create_point(40.0,80.0)));
3852</pre></div></div></li>
3853</ul>
3854
3855<ul>
3856
3857<li>
3858<p>The expected result is:</p>
3859
3860<div class="source">
3861<div class="source">
3862<pre>true
3863</pre></div></div></li>
3864</ul></div>
3865<div class="section">
3866<h3><a name="spatial_cell"></a>spatial_cell</h3>
3867
3868<ul>
3869
3870<li>
3871<p>Syntax:</p>
3872
3873<div class="source">
3874<div class="source">
3875<pre>spatial_cell(point1, point2, x_increment, y_increment)
3876</pre></div></div></li>
3877
3878<li>
3879<p>Returns the grid cell that <tt>point1</tt> belongs to.</p></li>
3880
3881<li>Arguments:
3882
3883<ul>
3884
3885<li><tt>point1</tt> : a <tt>point</tt> representing the point of interest that its grid cell will be returned.</li>
3886
3887<li><tt>point2</tt> : a <tt>point</tt> representing the origin of the grid.</li>
3888
3889<li><tt>x_increment</tt> : a <tt>double</tt>, represents X increments.</li>
3890
3891<li><tt>y_increment</tt> : a <tt>double</tt>, represents Y increments.</li>
3892 </ul></li>
3893
3894<li>Return Value:
3895
3896<ul>
3897
3898<li>a <tt>rectangle</tt> representing the grid cell that <tt>point1</tt> belongs to,</li>
3899
3900<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3901
3902<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3903
3904<li>a type error will be raised if:
3905
3906<ul>
3907
3908<li>the first or second argument is any other non-point value,</li>
3909
3910<li>or, the second or third argument is any other non-double value.</li>
3911 </ul></li>
3912 </ul></li>
3913
3914<li>
3915<p>Example:</p>
3916
3917<div class="source">
3918<div class="source">
3919<pre>spatial_cell(point(&quot;39.28,70.48&quot;), create_point(20.0,50.0), 5.5, 6.0);
3920</pre></div></div></li>
3921</ul>
3922
3923<ul>
3924
3925<li>
3926<p>The expected result is:</p>
3927
3928<div class="source">
3929<div class="source">
3930<pre>rectangle(&quot;36.5,68.0 42.0,74.0&quot;);
3931</pre></div></div></li>
3932</ul>
3933<!-- ! Licensed to the Apache Software Foundation (ASF) under one
3934 ! or more contributor license agreements. See the NOTICE file
3935 ! distributed with this work for additional information
3936 ! regarding copyright ownership. The ASF licenses this file
3937 ! to you under the Apache License, Version 2.0 (the
3938 ! "License"); you may not use this file except in compliance
3939 ! with the License. You may obtain a copy of the License at
3940 !
3941 ! http://www.apache.org/licenses/LICENSE-2.0
3942 !
3943 ! Unless required by applicable law or agreed to in writing,
3944 ! software distributed under the License is distributed on an
3945 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
3946 ! KIND, either express or implied. See the License for the
3947 ! specific language governing permissions and limitations
3948 ! under the License.
3949 ! --></div></div>
3950<div class="section">
3951<h2><a name="Similarity_Functions"></a><a name="SimilarityFunctions" id="SimilarityFunctions">Similarity Functions</a></h2>
3952<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>
3953<div class="section">
3954<h3><a name="edit_distance"></a>edit_distance</h3>
3955
3956<ul>
3957
3958<li>
3959<p>Syntax:</p>
3960
3961<div class="source">
3962<div class="source">
3963<pre>edit_distance(expression1, expression2)
3964</pre></div></div></li>
3965
3966<li>
3967<p>Returns the edit distance of <tt>expression1</tt> and <tt>expression2</tt>.</p></li>
3968
3969<li>Arguments:
3970
3971<ul>
3972
3973<li><tt>expression1</tt> : a <tt>string</tt> or a homogeneous <tt>array</tt> of a comparable item type.</li>
3974
3975<li><tt>expression2</tt> : The same type as <tt>expression1</tt>.</li>
3976 </ul></li>
3977
3978<li>Return Value:
3979
3980<ul>
3981
3982<li>an <tt>bigint</tt> that represents the edit distance between <tt>expression1</tt> and <tt>expression2</tt>,</li>
3983
3984<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3985
3986<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3987
3988<li>any other non-string input value will cause a type error.</li>
3989 </ul></li>
3990
3991<li>Note: an <a href="similarity.html#UsingIndexesToSupportSimilarityQueries">n_gram index</a> can be utilized for this function.</li>
3992
3993<li>
3994<p>Example:</p>
3995
3996<div class="source">
3997<div class="source">
3998<pre>edit_distance(&quot;SuzannaTillson&quot;, &quot;Suzanna Tilson&quot;);
3999</pre></div></div></li>
4000</ul>
4001
4002<ul>
4003
4004<li>
4005<p>The expected result is:</p>
4006
4007<div class="source">
4008<div class="source">
4009<pre>2
4010</pre></div></div></li>
4011</ul></div>
4012<div class="section">
4013<h3><a name="edit_distance_check"></a>edit_distance_check</h3>
4014
4015<ul>
4016
4017<li>
4018<p>Syntax:</p>
4019
4020<div class="source">
4021<div class="source">
4022<pre>edit_distance_check(expression1, expression2, threshold)
4023</pre></div></div></li>
4024
4025<li>
4026<p>Checks whether the edit distance of <tt>expression1</tt> and <tt>expression2</tt> is within a given threshold.</p></li>
4027
4028<li>
4029<p>Arguments:</p>
4030
4031<ul>
4032
4033<li><tt>expression1</tt> : a <tt>string</tt> or a homogeneous <tt>array</tt> of a comparable item type.</li>
4034
4035<li><tt>expression2</tt> : The same type as <tt>expression1</tt>.</li>
4036
4037<li><tt>threshold</tt> : a <tt>bigint</tt> that represents the distance threshold.</li>
4038 </ul></li>
4039
4040<li>Return Value:
4041
4042<ul>
4043
4044<li>an <tt>array</tt> with two items:
4045
4046<ul>
4047
4048<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>
4049
4050<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>
4051
4052<li>If the first item is false, then the second item is set to 2147483647.</li>
4053 </ul></li>
4054
4055<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
4056
4057<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
4058
4059<li>a type error will be raised if:
4060
4061<ul>
4062
4063<li>the first or second argument is any other non-string value,</li>
4064
4065<li>or, the third argument is any other non-bigint value.</li>
4066 </ul></li>
4067 </ul></li>
4068
4069<li>Note: an <a href="similarity.html#UsingIndexesToSupportSimilarityQueries">n_gram index</a> can be utilized for this function.</li>
4070
4071<li>
4072<p>Example:</p>
4073
4074<div class="source">
4075<div class="source">
4076<pre>edit_distance_check(&quot;happy&quot;,&quot;hapr&quot;,2);
4077</pre></div></div></li>
4078</ul>
4079
4080<ul>
4081
4082<li>
4083<p>The expected result is:</p>
4084
4085<div class="source">
4086<div class="source">
4087<pre>[ true, 2 ]
4088</pre></div></div></li>
4089</ul></div>
4090<div class="section">
4091<h3><a name="edit_distance_contains"></a>edit_distance_contains</h3>
4092
4093<ul>
4094
4095<li>
4096<p>Syntax:</p>
4097
4098<div class="source">
4099<div class="source">
4100<pre>edit_distance_contains(expression1, expression2, threshold)
4101</pre></div></div></li>
4102
4103<li>
4104<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></li>
4105
4106<li>
4107<p>Arguments:</p>
4108
4109<ul>
4110
4111<li><tt>expression1</tt> : a <tt>string</tt> or a homogeneous <tt>array</tt> of a comparable item type.</li>
4112
4113<li><tt>expression2</tt> : The same type as <tt>expression1</tt>.</li>
4114
4115<li><tt>threshold</tt> : a <tt>bigint</tt> that represents the distance threshold.</li>
4116 </ul></li>
4117
4118<li>Return Value:
4119
4120<ul>
4121
4122<li>an <tt>array</tt> with two items:
4123
4124<ul>
4125
4126<li>The first item contains a <tt>boolean</tt> value representing whether <tt>expression1</tt> can contain <tt>expression2</tt>.</li>
4127
4128<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>
4129 </ul></li>
4130
4131<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
4132
4133<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
4134
4135<li>a type error will be raised if:
4136
4137<ul>
4138
4139<li>the first or second argument is any other non-string value,</li>
4140
4141<li>or, the third argument is any other non-bigint value.</li>
4142 </ul></li>
4143 </ul></li>
4144
4145<li>Note: an <a href="similarity.html#UsingIndexesToSupportSimilarityQueries">n_gram index</a> can be utilized for this function.</li>
4146
4147<li>
4148<p>Example:</p>
4149
4150<div class="source">
4151<div class="source">
4152<pre>edit_distance_contains(&quot;happy&quot;,&quot;hapr&quot;,2);
4153</pre></div></div></li>
4154</ul>
4155
4156<ul>
4157
4158<li>
4159<p>The expected result is:</p>
4160
4161<div class="source">
4162<div class="source">
4163<pre>[ true, 1 ]
4164</pre></div></div></li>
4165</ul></div>
4166<div class="section">
4167<h3><a name="similarity_jaccard"></a>similarity_jaccard</h3>
4168
4169<ul>
4170
4171<li>
4172<p>Syntax:</p>
4173
4174<div class="source">
4175<div class="source">
4176<pre>similarity_jaccard(array1, array2)
4177</pre></div></div></li>
4178
4179<li>
4180<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></li>
4181
4182<li>Arguments:
4183
4184<ul>
4185
4186<li><tt>array1</tt> : an <tt>array</tt> or <tt>multiset</tt>.</li>
4187
4188<li><tt>array2</tt> : an <tt>array</tt> or <tt>multiset</tt>.</li>
4189 </ul></li>
4190
4191<li>Return Value:
4192
4193<ul>
4194
4195<li>a <tt>float</tt> that represents the Jaccard similarity of <tt>array1</tt> and <tt>array2</tt>,</li>
4196
4197<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
4198
4199<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
4200
4201<li><tt>missing</tt> if any element in any input array is <tt>missing</tt>,</li>
4202
4203<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>
4204
4205<li>any other non-array input value or non-integer element in any input array will cause a type error.</li>
4206 </ul></li>
4207
4208<li>
4209<p>Note: a <a href="similarity.html#UsingIndexesToSupportSimilarityQueries">keyword index</a> can be utilized for this function.</p></li>
4210
4211<li>
4212<p>Example:</p>
4213
4214<div class="source">
4215<div class="source">
4216<pre>similarity_jaccard([1,5,8,9], [1,5,9,10]);
4217</pre></div></div></li>
4218</ul>
4219
4220<ul>
4221
4222<li>
4223<p>The expected result is:</p>
4224
4225<div class="source">
4226<div class="source">
4227<pre>0.6
4228</pre></div></div></li>
4229</ul></div>
4230<div class="section">
4231<h3><a name="similarity_jaccard_check"></a>similarity_jaccard_check</h3>
4232
4233<ul>
4234
4235<li>
4236<p>Syntax:</p>
4237
4238<div class="source">
4239<div class="source">
4240<pre>similarity_jaccard_check(array1, array2, threshold)
4241</pre></div></div></li>
4242
4243<li>
4244<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></li>
4245
4246<li>
4247<p>Arguments:</p>
4248
4249<ul>
4250
4251<li><tt>array1</tt> : an <tt>array</tt> or <tt>multiset</tt>.</li>
4252
4253<li><tt>array2</tt> : an <tt>array</tt> or <tt>multiset</tt>.</li>
4254
4255<li><tt>threshold</tt> : a <tt>double</tt> that represents the similarity threshold.</li>
4256 </ul></li>
4257
4258<li>Return Value:
4259
4260<ul>
4261
4262<li>an <tt>array</tt> with two items:
4263
4264<ul>
4265
4266<li>The first item contains a <tt>boolean</tt> value representing whether <tt>array1</tt> and <tt>array2</tt> are similar.</li>
4267
4268<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>
4269 </ul></li>
4270
4271<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
4272
4273<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
4274
4275<li><tt>missing</tt> if any element in any input array is <tt>missing</tt>,</li>
4276
4277<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>
4278
4279<li>a type error will be raised if: * the first or second argument is any other non-array value, * or, the third argument is any other non-double value.</li>
4280 </ul></li>
4281
4282<li>
4283<p>Note: a <a href="similarity.html#UsingIndexesToSupportSimilarityQueries">keyword index</a> can be utilized for this function.</p></li>
4284
4285<li>
4286<p>Example:</p>
4287
4288<div class="source">
4289<div class="source">
4290<pre>similarity_jaccard_check([1,5,8,9], [1,5,9,10], 0.6);
4291</pre></div></div></li>
4292</ul>
4293
4294<ul>
4295
4296<li>
4297<p>The expected result is:</p>
4298
4299<div class="source">
4300<div class="source">
4301<pre>[ false, 0.0 ]
4302</pre></div></div></li>
4303</ul>
4304<!-- ! Licensed to the Apache Software Foundation (ASF) under one
4305 ! or more contributor license agreements. See the NOTICE file
4306 ! distributed with this work for additional information
4307 ! regarding copyright ownership. The ASF licenses this file
4308 ! to you under the Apache License, Version 2.0 (the
4309 ! "License"); you may not use this file except in compliance
4310 ! with the License. You may obtain a copy of the License at
4311 !
4312 ! http://www.apache.org/licenses/LICENSE-2.0
4313 !
4314 ! Unless required by applicable law or agreed to in writing,
4315 ! software distributed under the License is distributed on an
4316 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
4317 ! KIND, either express or implied. See the License for the
4318 ! specific language governing permissions and limitations
4319 ! under the License.
4320 ! --></div></div>
4321<div class="section">
4322<h2><a name="Tokenizing_Functions"></a><a name="TokenizingFunctions" id="TokenizingFunctions">Tokenizing Functions</a></h2>
4323<div class="section">
4324<h3><a name="word_tokens"></a>word_tokens</h3>
4325
4326<ul>
4327
4328<li>
4329<p>Syntax:</p>
4330
4331<div class="source">
4332<div class="source">
4333<pre>word_tokens(string)
4334</pre></div></div></li>
4335
4336<li>
4337<p>Returns an array of word tokens of <tt>string</tt> using non_alphanumeric characters as delimiters.</p></li>
4338
4339<li>Arguments:
4340
4341<ul>
4342
4343<li><tt>string</tt> : a <tt>string</tt> that will be tokenized.</li>
4344 </ul></li>
4345
4346<li>Return Value:
4347
4348<ul>
4349
4350<li>an <tt>array</tt> of <tt>string</tt> word tokens,</li>
4351
4352<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
4353
4354<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
4355
4356<li>any other non-string input value will cause a type error.</li>
4357 </ul></li>
4358
4359<li>
4360<p>Example:</p>
4361
4362<div class="source">
4363<div class="source">
4364<pre>word_tokens(&quot;I like the phone, awesome!&quot;);
4365</pre></div></div></li>
4366</ul>
4367
4368<ul>
4369
4370<li>
4371<p>The expected result is:</p>
4372
4373<div class="source">
4374<div class="source">
4375<pre>[ &quot;i&quot;, &quot;like&quot;, &quot;the&quot;, &quot;phone&quot;, &quot;awesome&quot; ]
4376</pre></div></div></li>
4377</ul>
4378<!-- ! Licensed to the Apache Software Foundation (ASF) under one
4379 ! or more contributor license agreements. See the NOTICE file
4380 ! distributed with this work for additional information
4381 ! regarding copyright ownership. The ASF licenses this file
4382 ! to you under the Apache License, Version 2.0 (the
4383 ! "License"); you may not use this file except in compliance
4384 ! with the License. You may obtain a copy of the License at
4385 !
4386 ! http://www.apache.org/licenses/LICENSE-2.0
4387 !
4388 ! Unless required by applicable law or agreed to in writing,
4389 ! software distributed under the License is distributed on an
4390 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
4391 ! KIND, either express or implied. See the License for the
4392 ! specific language governing permissions and limitations
4393 ! under the License.
4394 ! --></div></div>
4395<div class="section">
4396<h2><a name="Temporal_Functions"></a><a name="TemporalFunctions" id="TemporalFunctions">Temporal Functions</a></h2>
4397<div class="section">
4398<h3><a name="get_yearget_monthget_dayget_hourget_minuteget_secondget_millisecond"></a>get_year/get_month/get_day/get_hour/get_minute/get_second/get_millisecond</h3>
4399
4400<ul>
4401
4402<li>
4403<p>Syntax:</p>
4404
4405<div class="source">
4406<div class="source">
4407<pre>get_year/get_month/get_day/get_hour/get_minute/get_second/get_millisecond(temporal_value)
4408</pre></div></div></li>
4409
4410<li>
4411<p>Accessors for accessing fields in a temporal value</p></li>
4412
4413<li>Arguments:
4414
4415<ul>
4416
4417<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>
4418 </ul></li>
4419
4420<li>Return Value:
4421
4422<ul>
4423
4424<li>an <tt>bigint</tt> value representing the field to be extracted,</li>
4425
4426<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
4427
4428<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
4429
4430<li>any other non-interval input value will cause a type error.</li>
4431 </ul></li>
4432
4433<li>
4434<p>Example:</p>
4435
4436<div class="source">
4437<div class="source">
4438<pre>{
4439 &quot;year&quot;: get_year(date(&quot;2010-10-30&quot;)),
4440 &quot;month&quot;: get_month(datetime(&quot;1987-11-19T23:49:23.938&quot;)),
4441 &quot;day&quot;: get_day(date(&quot;2010-10-30&quot;)),
4442 &quot;hour&quot;: get_hour(time(&quot;12:23:34.930+07:00&quot;)),
4443 &quot;min&quot;: get_minute(duration(&quot;P3Y73M632DT49H743M3948.94S&quot;)),
4444 &quot;second&quot;: get_second(datetime(&quot;1987-11-19T23:49:23.938&quot;)),
4445 &quot;ms&quot;: get_millisecond(duration(&quot;P3Y73M632DT49H743M3948.94S&quot;))
4446};
4447</pre></div></div></li>
4448</ul>
4449
4450<ul>
4451
4452<li>
4453<p>The expected result is:</p>
4454
4455<div class="source">
4456<div class="source">
4457<pre>{ &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 }
4458</pre></div></div></li>
4459</ul></div>
4460<div class="section">
4461<h3><a name="adjust_datetime_for_timezone"></a>adjust_datetime_for_timezone</h3>
4462
4463<ul>
4464
4465<li>
4466<p>Syntax:</p>
4467
4468<div class="source">
4469<div class="source">
4470<pre>adjust_datetime_for_timezone(datetime, string)
4471</pre></div></div></li>
4472
4473<li>
4474<p>Adjusts the given datetime <tt>datetime</tt> by applying the timezone information <tt>string</tt>.</p></li>
4475
4476<li>Arguments:
4477
4478<ul>
4479
4480<li><tt>datetime</tt> : a <tt>datetime</tt> value to be adjusted.</li>
4481
4482<li><tt>string</tt> : a <tt>string</tt> representing the timezone information.</li>
4483 </ul></li>
4484
4485<li>Return Value:
4486
4487<ul>
4488
4489<li>a <tt>string</tt> value representing the new datetime after being adjusted by the timezone information,</li>
4490
4491<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
4492
4493<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
4494
4495<li>a type error will be raised if:
4496
4497<ul>
4498
4499<li>the first argument is any other non-datetime value,</li>
4500
4501<li>or, the second argument is any other non-string value.</li>
4502 </ul></li>
4503 </ul></li>
4504
4505<li>
4506<p>Example:</p>
4507
4508<div class="source">
4509<div class="source">
4510<pre>adjust_datetime_for_timezone(datetime(&quot;2008-04-26T10:10:00&quot;), &quot;+08:00&quot;);
4511</pre></div></div></li>
4512</ul>
4513
4514<ul>
4515
4516<li>
4517<p>The expected result is:</p>
4518
4519<div class="source">
4520<div class="source">
4521<pre>&quot;2008-04-26T18:10:00.000+08:00&quot;
4522</pre></div></div></li>
4523</ul></div>
4524<div class="section">
4525<h3><a name="adjust_time_for_timezone"></a>adjust_time_for_timezone</h3>
4526
4527<ul>
4528
4529<li>
4530<p>Syntax:</p>
4531
4532<div class="source">
4533<div class="source">
4534<pre>adjust_time_for_timezone(time, string)
4535</pre></div></div></li>
4536
4537<li>
4538<p>Adjusts the given time <tt>time</tt> by applying the timezone information <tt>string</tt>.</p></li>
4539
4540<li>Arguments:
4541
4542<ul>
4543
4544<li><tt>time</tt> : a <tt>time</tt> value to be adjusted.</li>
4545
4546<li><tt>string</tt> : a <tt>string</tt> representing the timezone information.</li>
4547 </ul></li>
4548
4549<li>Return Value:
4550
4551<ul>
4552
4553<li>a <tt>string</tt> value representing the new time after being adjusted by the timezone information,</li>
4554
4555<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
4556
4557<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
4558
4559<li>a type error will be raised if:
4560
4561<ul>
4562
4563<li>the first argument is any other non-time value,</li>
4564
4565<li>or, the second argument is any other non-string value.</li>
4566 </ul></li>
4567 </ul></li>
4568
4569<li>
4570<p>Example:</p>
4571
4572<div class="source">
4573<div class="source">
4574<pre>adjust_time_for_timezone(get_time_from_datetime(datetime(&quot;2008-04-26T10:10:00&quot;)), &quot;+08:00&quot;);
4575</pre></div></div></li>
4576</ul>
4577
4578<ul>
4579
4580<li>
4581<p>The expected result is:</p>
4582
4583<div class="source">
4584<div class="source">
4585<pre>&quot;18:10:00.000+08:00&quot;
4586</pre></div></div></li>
4587</ul></div>
4588<div class="section">
4589<h3><a name="calendar_duration_from_datetime"></a>calendar_duration_from_datetime</h3>
4590
4591<ul>
4592
4593<li>
4594<p>Syntax:</p>
4595
4596<div class="source">
4597<div class="source">
4598<pre>calendar_duration_from_datetime(datetime, duration_value)
4599</pre></div></div></li>
4600
4601<li>
4602<p>Gets a user_friendly representation of the duration <tt>duration_value</tt> based on the given datetime <tt>datetime</tt>.</p></li>
4603
4604<li>Arguments:
4605
4606<ul>
4607
4608<li><tt>datetime</tt> : a <tt>datetime</tt> value to be used as the reference time point.</li>
4609
4610<li><tt>duration_value</tt> : a <tt>duration</tt> value to be converted.</li>
4611 </ul></li>
4612
4613<li>Return Value:
4614
4615<ul>
4616
4617<li>a <tt>duration</tt> value with the duration as <tt>duration_value</tt> but with a user_friendly representation,</li>
4618
4619<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
4620
4621<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
4622
4623<li>a type error will be raised if:
4624
4625<ul>
4626
4627<li>the first argument is any other non-datetime value,</li>
4628
4629<li>or, the second argument is any other non-duration input value.</li>
4630 </ul></li>
4631 </ul></li>
4632
4633<li>
4634<p>Example:</p>
4635
4636<div class="source">
4637<div class="source">
4638<pre>calendar_duration_from_datetime(
4639 datetime(&quot;2016-03-26T10:10:00&quot;),
4640 datetime(&quot;2016-03-26T10:10:00&quot;) - datetime(&quot;2011-01-01T00:00:00&quot;)
4641);
4642</pre></div></div></li>
4643
4644<li>
4645<p>The expected result is:</p>
4646
4647<div class="source">
4648<div class="source">
4649<pre>duration(&quot;P5Y2M24DT10H10M&quot;)
4650</pre></div></div></li>
4651</ul></div>
4652<div class="section">
4653<h3><a name="get_year_month_durationget_day_time_duration"></a>get_year_month_duration/get_day_time_duration</h3>
4654
4655<ul>
4656
4657<li>
4658<p>Syntax:</p>
4659
4660<div class="source">
4661<div class="source">
4662<pre>get_year_month_duration/get_day_time_duration(duration_value)
4663</pre></div></div></li>
4664
4665<li>
4666<p>Extracts the correct <tt>duration</tt> subtype from <tt>duration_value</tt>.</p></li>
4667
4668<li>Arguments:
4669
4670<ul>
4671
4672<li><tt>duration_value</tt> : a <tt>duration</tt> value to be converted.</li>
4673 </ul></li>
4674
4675<li>Return Value:
4676
4677<ul>
4678
4679<li>a <tt>year_month_duration</tt> value or a <tt>day_time_duration</tt> value,</li>
4680
4681<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
4682
4683<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
4684
4685<li>any other non-duration input value will cause a type error.</li>
4686 </ul></li>
4687
4688<li>
4689<p>Example:</p>
4690
4691<div class="source">
4692<div class="source">
4693<pre>get_year_month_duration(duration(&quot;P12M50DT10H&quot;));
4694</pre></div></div></li>
4695</ul>
4696
4697<ul>
4698
4699<li>
4700<p>The expected result is:</p>
4701
4702<div class="source">
4703<div class="source">
4704<pre>year_month_duration(&quot;P1Y&quot;)
4705</pre></div></div></li>
4706</ul></div>
4707<div class="section">
4708<h3><a name="months_from_year_month_durationmilliseconds_from_day_time_duration"></a>months_from_year_month_duration/milliseconds_from_day_time_duration</h3>
4709
4710<ul>
4711
4712<li>
4713<p>Syntax:</p>
4714
4715<div class="source">
4716<div class="source">
4717<pre>months_from_year_month_duration/milliseconds_from_day_time_duration(duration_value)
4718</pre></div></div></li>
4719
4720<li>
4721<p>Extracts the number of months or the number of milliseconds from the <tt>duration</tt> subtype.</p></li>
4722
4723<li>Arguments:
4724
4725<ul>
4726
4727<li><tt>duration_value</tt> : a <tt>duration</tt> of the correct subtype.</li>
4728 </ul></li>
4729
4730<li>Return Value:
4731
4732<ul>
4733
4734<li>an <tt>bigint</tt> representing the number or months/milliseconds,</li>
4735
4736<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
4737
4738<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
4739
4740<li>any other non-duration input value will cause a type error.</li>
4741 </ul></li>
4742
4743<li>
4744<p>Example:</p>
4745
4746<div class="source">
4747<div class="source">
4748<pre>months_from_year_month_duration(get_year_month_duration(duration(&quot;P5Y7MT50M&quot;)));
4749</pre></div></div></li>
4750</ul>
4751
4752<ul>
4753
4754<li>
4755<p>The expected result is:</p>
4756
4757<div class="source">
4758<div class="source">
4759<pre>67
4760</pre></div></div></li>
4761</ul></div>
4762<div class="section">
4763<h3><a name="duration_from_monthsduration_from_ms"></a>duration_from_months/duration_from_ms</h3>
4764
4765<ul>
4766
4767<li>
4768<p>Syntax:</p>
4769
4770<div class="source">
4771<div class="source">
4772<pre>duration_from_months/duration_from_ms(number_value)
4773</pre></div></div></li>
4774
4775<li>
4776<p>Creates a <tt>duration</tt> from <tt>number_value</tt>.</p></li>
4777
4778<li>Arguments:
4779
4780<ul>
4781
4782<li><tt>number_value</tt> : a <tt>bigint</tt> representing the number of months/milliseconds</li>
4783 </ul></li>
4784
4785<li>Return Value:
4786
4787<ul>
4788
4789<li>a <tt>duration</tt> containing <tt>number_value</tt> value for months/milliseconds,</li>
4790
4791<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
4792
4793<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
4794
4795<li>any other non-duration input value will cause a type error.</li>
4796 </ul></li>
4797
4798<li>
4799<p>Example:</p>
4800
4801<div class="source">
4802<div class="source">
4803<pre>duration_from_months(8);
4804</pre></div></div></li>
4805
4806<li>
4807<p>The expected result is:</p>
4808
4809<div class="source">
4810<div class="source">
4811<pre>duration(&quot;P8M&quot;)
4812</pre></div></div></li>
4813</ul></div>
4814<div class="section">
4815<h3><a name="duration_from_interval"></a>duration_from_interval</h3>
4816
4817<ul>
4818
4819<li>
4820<p>Syntax:</p>
4821
4822<div class="source">
4823<div class="source">
4824<pre>duration_from_interval(interval_value)
4825</pre></div></div></li>
4826
4827<li>
4828<p>Creates a <tt>duration</tt> from <tt>interval_value</tt>.</p></li>
4829
4830<li>Arguments:
4831
4832<ul>
4833
4834<li><tt>interval_value</tt> : an <tt>interval</tt> value</li>
4835 </ul></li>
4836
4837<li>Return Value:
4838
4839<ul>
4840
4841<li>a <tt>duration</tt> representing the time in the <tt>interval_value</tt></li>
4842
4843<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
4844
4845<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
4846
4847<li>any other non-duration input value will cause a type error.</li>
4848 </ul></li>
4849
4850<li>
4851<p>Example:</p>
4852
4853<div class="source">
4854<div class="source">
4855<pre>{
4856 &quot;dr1&quot; : duration_from_interval(interval(date(&quot;2010-10-30&quot;), date(&quot;2010-12-21&quot;))),
4857 &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;))),
4858 &quot;dr3&quot; : duration_from_interval(interval(time(&quot;12:32:38&quot;), time(&quot;20:29:20&quot;))),
4859 &quot;dr4&quot; : duration_from_interval(null)
4860};
4861</pre></div></div></li>
4862
4863<li>
4864<p>The expected result is:</p>
4865
4866<div class="source">
4867<div class="source">
4868<pre>{
4869 &quot;dr1&quot;: day_time_duration(&quot;P52D&quot;),
4870 &quot;dr2&quot;: day_time_duration(&quot;P31DT1H1M1.111S&quot;),
4871 &quot;dr3&quot;: day_time_duration(&quot;PT7H56M42S&quot;),
4872 &quot;dr4&quot;: null
4873}
4874</pre></div></div></li>
4875</ul></div>
4876<div class="section">
4877<h3><a name="current_date"></a>current_date</h3>
4878
4879<ul>
4880
4881<li>
4882<p>Syntax:</p>
4883
4884<div class="source">
4885<div class="source">
4886<pre>current_date()
4887</pre></div></div></li>
4888
4889<li>
4890<p>Gets the current date.</p></li>
4891
4892<li>Arguments: None</li>
4893
4894<li>Return Value:
4895
4896<ul>
4897
4898<li>a <tt>date</tt> value of the date when the function is called.</li>
4899 </ul></li>
4900</ul></div>
4901<div class="section">
4902<h3><a name="current_time"></a>current_time</h3>
4903
4904<ul>
4905
4906<li>
4907<p>Syntax:</p>
4908
4909<div class="source">
4910<div class="source">
4911<pre>current_time()
4912</pre></div></div></li>
4913
4914<li>
4915<p>Get the current time</p></li>
4916
4917<li>Arguments: None</li>
4918
4919<li>Return Value:
4920
4921<ul>
4922
4923<li>a <tt>time</tt> value of the time when the function is called.</li>
4924 </ul></li>
4925</ul></div>
4926<div class="section">
4927<h3><a name="current_datetime"></a>current_datetime</h3>
4928
4929<ul>
4930
4931<li>
4932<p>Syntax:</p>
4933
4934<div class="source">
4935<div class="source">
4936<pre>current_datetime()
4937</pre></div></div></li>
4938
4939<li>
4940<p>Get the current datetime</p></li>
4941
4942<li>Arguments: None</li>
4943
4944<li>Return Value:
4945
4946<ul>
4947
4948<li>a <tt>datetime</tt> value of the datetime when the function is called.</li>
4949 </ul></li>
4950</ul></div>
4951<div class="section">
4952<h3><a name="get_date_from_datetime"></a>get_date_from_datetime</h3>
4953
4954<ul>
4955
4956<li>
4957<p>Syntax:</p>
4958
4959<div class="source">
4960<div class="source">
4961<pre>get_date_from_datetime(datetime)
4962</pre></div></div></li>
4963
4964<li>
4965<p>Gets the date value from the given datetime value <tt>datetime</tt>.</p></li>
4966
4967<li>Arguments:
4968
4969<ul>
4970
4971<li><tt>datetime</tt>: a <tt>datetime</tt> value to be extracted from.</li>
4972 </ul></li>
4973
4974<li>Return Value:
4975
4976<ul>
4977
4978<li>a <tt>date</tt> value from the datetime,</li>
4979
4980<li>any other non-datetime input value will cause a type error.</li>
4981 </ul></li>
4982</ul></div>
4983<div class="section">
4984<h3><a name="get_time_from_datetime"></a>get_time_from_datetime</h3>
4985
4986<ul>
4987
4988<li>
4989<p>Syntax:</p>
4990
4991<div class="source">
4992<div class="source">
4993<pre>get_time_from_datetime(datetime)
4994</pre></div></div></li>
4995
4996<li>
4997<p>Get the time value from the given datetime value <tt>datetime</tt></p></li>
4998
4999<li>Arguments:
5000
5001<ul>
5002
5003<li><tt>datetime</tt>: a <tt>datetime</tt> value to be extracted from.</li>
5004 </ul></li>
5005
5006<li>Return Value:
5007
5008<ul>
5009
5010<li>a <tt>time</tt> value from the datetime.</li>
5011
5012<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5013
5014<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5015
5016<li>any other non-datetime input value will cause a type error.</li>
5017 </ul></li>
5018
5019<li>
5020<p>Example:</p>
5021
5022<div class="source">
5023<div class="source">
5024<pre>get_time_from_datetime(datetime(&quot;2016-03-26T10:10:00&quot;));
5025</pre></div></div></li>
5026
5027<li>
5028<p>The expected result is:</p>
5029
5030<div class="source">
5031<div class="source">
5032<pre>time(&quot;10:10:00.000Z&quot;)
5033</pre></div></div></li>
5034</ul></div>
5035<div class="section">
5036<h3><a name="day_of_week"></a>day_of_week</h3>
5037
5038<ul>
5039
5040<li>
5041<p>Syntax:</p>
5042
5043<div class="source">
5044<div class="source">
5045<pre>day_of_week(date)
5046</pre></div></div></li>
5047
5048<li>
5049<p>Finds the day of the week for a given date (1_7)</p></li>
5050
5051<li>Arguments:
5052
5053<ul>
5054
5055<li><tt>date</tt>: a <tt>date</tt> value (Can also be a <tt>datetime</tt>)</li>
5056 </ul></li>
5057
5058<li>Return Value:
5059
5060<ul>
5061
5062<li>an <tt>tinyint</tt> representing the day of the week (1_7),</li>
5063
5064<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5065
5066<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5067
5068<li>any other non-date input value will cause a type error.</li>
5069 </ul></li>
5070
5071<li>
5072<p>Example:</p>
5073
5074<div class="source">
5075<div class="source">
5076<pre>day_of_week(datetime(&quot;2012-12-30T12:12:12.039Z&quot;));
5077</pre></div></div></li>
5078</ul>
5079
5080<ul>
5081
5082<li>
5083<p>The expected result is:</p>
5084
5085<div class="source">
5086<div class="source">
5087<pre>7
5088</pre></div></div></li>
5089</ul></div>
5090<div class="section">
5091<h3><a name="date_from_unix_time_in_days"></a>date_from_unix_time_in_days</h3>
5092
5093<ul>
5094
5095<li>
5096<p>Syntax:</p>
5097
5098<div class="source">
5099<div class="source">
5100<pre>date_from_unix_time_in_days(numeric_value)
5101</pre></div></div></li>
5102
5103<li>
5104<p>Gets a date representing the time after <tt>numeric_value</tt> days since 1970_01_01.</p></li>
5105
5106<li>Arguments:
5107
5108<ul>
5109
5110<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>
5111 </ul></li>
5112
5113<li>Return Value:
5114
5115<ul>
5116
5117<li>a <tt>date</tt> value as the time after <tt>numeric_value</tt> days since 1970-01-01,</li>
5118
5119<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5120
5121<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5122
5123<li>any other non-numeric input value will cause a type error.</li>
5124 </ul></li>
5125</ul></div>
5126<div class="section">
5127<h3><a name="datetime_from_unix_time_in_ms"></a>datetime_from_unix_time_in_ms</h3>
5128
5129<ul>
5130
5131<li>
5132<p>Syntax:</p>
5133
5134<div class="source">
5135<div class="source">
5136<pre>datetime_from_unix_time_in_ms(numeric_value)
5137</pre></div></div></li>
5138
5139<li>
5140<p>Gets a datetime representing the time after <tt>numeric_value</tt> milliseconds since 1970_01_01T00:00:00Z.</p></li>
5141
5142<li>Arguments:
5143
5144<ul>
5145
5146<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>
5147 </ul></li>
5148
5149<li>Return Value:
5150
5151<ul>
5152
5153<li>a <tt>datetime</tt> value as the time after <tt>numeric_value</tt> milliseconds since 1970-01-01T00:00:00Z,</li>
5154
5155<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5156
5157<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5158
5159<li>any other non-numeric input value will cause a type error.</li>
5160 </ul></li>
5161</ul></div>
5162<div class="section">
5163<h3><a name="datetime_from_unix_time_in_secs"></a>datetime_from_unix_time_in_secs</h3>
5164
5165<ul>
5166
5167<li>
5168<p>Syntax:</p>
5169
5170<div class="source">
5171<div class="source">
5172<pre>datetime_from_unix_time_in_secs(numeric_value)
5173</pre></div></div></li>
5174
5175<li>
5176<p>Gets a datetime representing the time after <tt>numeric_value</tt> seconds since 1970_01_01T00:00:00Z.</p></li>
5177
5178<li>Arguments:
5179
5180<ul>
5181
5182<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>
5183 </ul></li>
5184
5185<li>Return Value:
5186
5187<ul>
5188
5189<li>a <tt>datetime</tt> value as the time after <tt>numeric_value</tt> seconds since 1970_01_01T00:00:00Z,</li>
5190
5191<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5192
5193<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5194
5195<li>any other non-numeric input value will cause a type error.</li>
5196 </ul></li>
5197</ul></div>
5198<div class="section">
5199<h3><a name="datetime_from_date_time"></a>datetime_from_date_time</h3>
5200
5201<ul>
5202
5203<li>Syntax:</li>
5204</ul>
5205<p>datetime_from_date_time(date,time)</p>
5206
5207<ul>
5208
5209<li>Gets a datetime representing the combination of <tt>date</tt> and <tt>time</tt>
5210
5211<ul>
5212
5213<li>Arguments:</li>
5214
5215<li><tt>date</tt>: a <tt>date</tt> value</li>
5216
5217<li><tt>time</tt> a <tt>time</tt> value</li>
5218 </ul></li>
5219
5220<li>Return Value:
5221
5222<ul>
5223
5224<li>a <tt>datetime</tt> value by combining <tt>date</tt> and <tt>time</tt>,</li>
5225
5226<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
5227
5228<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
5229
5230<li>a type error will be raised if
5231
5232<ul>
5233
5234<li>the first argument is any other non-date value,</li>
5235
5236<li>or, the second argument is any other non-time value.</li>
5237 </ul></li>
5238 </ul></li>
5239</ul></div>
5240<div class="section">
5241<h3><a name="time_from_unix_time_in_ms"></a>time_from_unix_time_in_ms</h3>
5242
5243<ul>
5244
5245<li>
5246<p>Syntax:</p>
5247
5248<div class="source">
5249<div class="source">
5250<pre>time_from_unix_time_in_ms(numeric_value)
5251</pre></div></div></li>
5252
5253<li>
5254<p>Gets a time representing the time after <tt>numeric_value</tt> milliseconds since 00:00:00.000Z.</p></li>
5255
5256<li>Arguments:
5257
5258<ul>
5259
5260<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>
5261 </ul></li>
5262
5263<li>Return Value:
5264
5265<ul>
5266
5267<li>a <tt>time</tt> value as the time after <tt>numeric_value</tt> milliseconds since 00:00:00.000Z,</li>
5268
5269<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5270
5271<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5272
5273<li>any other non-numeric input value will cause a type error.</li>
5274 </ul></li>
5275
5276<li>
5277<p>Example:</p>
5278
5279<div class="source">
5280<div class="source">
5281<pre>{
5282 &quot;date&quot;: date_from_unix_time_in_days(15800),
5283 &quot;datetime&quot;: datetime_from_unix_time_in_ms(1365139700000),
5284 &quot;time&quot;: time_from_unix_time_in_ms(3748)
5285};
5286</pre></div></div></li>
5287</ul>
5288
5289<ul>
5290
5291<li>
5292<p>The expected result is:</p>
5293
5294<div class="source">
5295<div class="source">
5296<pre>{ &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;) }
5297</pre></div></div></li>
5298</ul></div>
5299<div class="section">
5300<h3><a name="unix_time_from_date_in_days"></a>unix_time_from_date_in_days</h3>
5301
5302<ul>
5303
5304<li>
5305<p>Syntax:</p>
5306
5307<div class="source">
5308<div class="source">
5309<pre>unix_time_from_date_in_days(date_value)
5310</pre></div></div></li>
5311
5312<li>
5313<p>Gets an integer value representing the number of days since 1970_01_01 for <tt>date_value</tt>.</p></li>
5314
5315<li>Arguments:
5316
5317<ul>
5318
5319<li><tt>date_value</tt>: a <tt>date</tt> value.</li>
5320 </ul></li>
5321
5322<li>Return Value:
5323
5324<ul>
5325
5326<li>a <tt>bigint</tt> value representing the number of days,</li>
5327
5328<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5329
5330<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5331
5332<li>any other non-date input value will cause a type error.</li>
5333 </ul></li>
5334</ul></div>
5335<div class="section">
5336<h3><a name="unix_time_from_datetime_in_ms"></a>unix_time_from_datetime_in_ms</h3>
5337
5338<ul>
5339
5340<li>
5341<p>Syntax:</p>
5342
5343<div class="source">
5344<div class="source">
5345<pre>unix_time_from_datetime_in_ms(datetime_value)
5346</pre></div></div></li>
5347
5348<li>
5349<p>Gets an integer value representing the time in milliseconds since 1970_01_01T00:00:00Z for <tt>datetime_value</tt>.</p></li>
5350
5351<li>Arguments:
5352
5353<ul>
5354
5355<li><tt>datetime_value</tt> : a <tt>datetime</tt> value.</li>
5356 </ul></li>
5357
5358<li>Return Value:
5359
5360<ul>
5361
5362<li>a <tt>bigint</tt> value representing the number of milliseconds,</li>
5363
5364<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5365
5366<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5367
5368<li>any other non-datetime input value will cause a type error.</li>
5369 </ul></li>
5370</ul></div>
5371<div class="section">
5372<h3><a name="unix_time_from_datetime_in_secs"></a>unix_time_from_datetime_in_secs</h3>
5373
5374<ul>
5375
5376<li>
5377<p>Syntax:</p>
5378
5379<div class="source">
5380<div class="source">
5381<pre>unix_time_from_datetime_in_secs(datetime_value)
5382</pre></div></div></li>
5383
5384<li>
5385<p>Gets an integer value representing the time in seconds since 1970_01_01T00:00:00Z for <tt>datetime_value</tt>.</p></li>
5386
5387<li>Arguments:
5388
5389<ul>
5390
5391<li><tt>datetime_value</tt> : a <tt>datetime</tt> value.</li>
5392 </ul></li>
5393
5394<li>Return Value:
5395
5396<ul>
5397
5398<li>a <tt>bigint</tt> value representing the number of seconds,</li>
5399
5400<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5401
5402<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5403
5404<li>any other non-datetime input value will cause a type error.</li>
5405 </ul></li>
5406</ul></div>
5407<div class="section">
5408<h3><a name="unix_time_from_time_in_ms"></a>unix_time_from_time_in_ms</h3>
5409
5410<ul>
5411
5412<li>
5413<p>Syntax:</p>
5414
5415<div class="source">
5416<div class="source">
5417<pre>unix_time_from_time_in_ms(time_value)
5418</pre></div></div></li>
5419
5420<li>
5421<p>Gets an integer value representing the time the milliseconds since 00:00:00.000Z for <tt>time_value</tt>.</p></li>
5422
5423<li>Arguments:
5424
5425<ul>
5426
5427<li><tt>time_value</tt> : a <tt>time</tt> value.</li>
5428 </ul></li>
5429
5430<li>Return Value:
5431
5432<ul>
5433
5434<li>a <tt>bigint</tt> value representing the number of milliseconds,</li>
5435
5436<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5437
5438<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5439
5440<li>any other non-datetime input value will cause a type error.</li>
5441 </ul></li>
5442
5443<li>
5444<p>Example:</p>
5445
5446<div class="source">
5447<div class="source">
5448<pre>{
5449 &quot;date&quot;: date_from_unix_time_in_days(15800),
5450 &quot;datetime&quot;: datetime_from_unix_time_in_ms(1365139700000),
5451 &quot;time&quot;: time_from_unix_time_in_ms(3748)
5452}
5453</pre></div></div></li>
5454</ul>
5455
5456<ul>
5457
5458<li>
5459<p>The expected result is:</p>
5460
5461<div class="source">
5462<div class="source">
5463<pre>{ &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;) }
5464</pre></div></div></li>
5465</ul></div>
5466<div class="section">
5467<h3><a name="parse_dateparse_timeparse_datetime"></a>parse_date/parse_time/parse_datetime</h3>
5468
5469<ul>
5470
5471<li>Syntax:</li>
5472</ul>
5473<p>parse_date/parse_time/parse_datetime(date,formatting_expression)</p>
5474
5475<ul>
5476
5477<li>Creates a <tt>date/time/date_time</tt> value by treating <tt>date</tt> with formatting <tt>formatting_expression</tt></li>
5478
5479<li>Arguments:
5480
5481<ul>
5482
5483<li><tt>date</tt>: a <tt>string</tt> value representing the <tt>date/time/datetime</tt>.</li>
5484
5485<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>
5486
5487<li><tt>h</tt> hours</li>
5488
5489<li><tt>m</tt> minutes</li>
5490
5491<li><tt>s</tt> seconds</li>
5492
5493<li><tt>n</tt> milliseconds</li>
5494
5495<li><tt>a</tt> am/pm</li>
5496
5497<li><tt>z</tt> timezone</li>
5498
5499<li><tt>Y</tt> year</li>
5500
5501<li><tt>M</tt> month</li>
5502
5503<li><tt>D</tt> day</li>
5504
5505<li><tt>W</tt> weekday</li>
5506
5507<li><tt>_</tt>, <tt>'</tt>, <tt>/</tt>, <tt>.</tt>, <tt>,</tt>, <tt>T</tt> seperators for both time and date</li>
5508 </ul></li>
5509
5510<li>Return Value:
5511
5512<ul>
5513
5514<li>a <tt>date/time/date_time</tt> value corresponding to <tt>date</tt>,</li>
5515
5516<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
5517
5518<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
5519
5520<li>a type error will be raised if:</li>
5521
5522<li>the first argument is any other non-date value,</li>
5523
5524<li>the second argument is any other non-string value.</li>
5525 </ul></li>
5526
5527<li>
5528<p>Example:</p>
5529
5530<div class="source">
5531<div class="source">
5532<pre>parse_time(&quot;30:30&quot;,&quot;m:s&quot;);
5533</pre></div></div></li>
5534
5535<li>
5536<p>The expected result is:</p>
5537
5538<div class="source">
5539<div class="source">
5540<pre>time(&quot;00:30:30.000Z&quot;)
5541</pre></div></div></li>
5542</ul></div>
5543<div class="section">
5544<h3><a name="print_dateprint_timeprint_datetime"></a>print_date/print_time/print_datetime</h3>
5545
5546<ul>
5547
5548<li>
5549<p>Syntax:</p>
5550
5551<div class="source">
5552<div class="source">
5553<pre>print_date/print_time/print_datetime(date,formatting_expression)
5554</pre></div></div></li>
5555
5556<li>
5557<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></li>
5558
5559<li>Arguments:
5560
5561<ul>
5562
5563<li><tt>date</tt>: a <tt>date/time/datetime</tt> value.</li>
5564
5565<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>
5566
5567<li><tt>h</tt> hours</li>
5568
5569<li><tt>m</tt> minutes</li>
5570
5571<li><tt>s</tt> seconds</li>
5572
5573<li><tt>n</tt> milliseconds</li>
5574
5575<li><tt>a</tt> am/pm</li>
5576
5577<li><tt>z</tt> timezone</li>
5578
5579<li><tt>Y</tt> year</li>
5580
5581<li><tt>M</tt> month</li>
5582
5583<li><tt>D</tt> day</li>
5584
5585<li><tt>W</tt> weekday</li>
5586
5587<li><tt>_</tt>, <tt>'</tt>, <tt>/</tt>, <tt>.</tt>, <tt>,</tt>, <tt>T</tt> seperators for both time and date</li>
5588 </ul></li>
5589
5590<li>Return Value:
5591
5592<ul>
5593
5594<li>a <tt>string</tt> value corresponding to <tt>date</tt>,</li>
5595
5596<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
5597
5598<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
5599
5600<li>a type error will be raised if:
5601
5602<ul>
5603
5604<li>the first argument is any other non-date value,</li>
5605
5606<li>the second argument is any other non-string value.</li>
5607 </ul></li>
5608 </ul></li>
5609
5610<li>
5611<p>Example:</p>
5612
5613<div class="source">
5614<div class="source">
5615<pre>print_time(time(&quot;00:30:30.000Z&quot;),&quot;m:s&quot;);
5616</pre></div></div></li>
5617
5618<li>
5619<p>The expected result is:</p>
5620
5621<div class="source">
5622<div class="source">
5623<pre>&quot;30:30&quot;
5624</pre></div></div></li>
5625</ul></div>
5626<div class="section">
5627<h3><a name="get_interval_start_get_interval_end"></a>get_interval_start, get_interval_end</h3>
5628
5629<ul>
5630
5631<li>
5632<p>Syntax:</p>
5633
5634<div class="source">
5635<div class="source">
5636<pre>get_interval_start/get_interval_end(interval)
5637</pre></div></div></li>
5638
5639<li>
5640<p>Gets the start/end of the given interval.</p></li>
5641
5642<li>Arguments:
5643
5644<ul>
5645
5646<li><tt>interval</tt>: the interval to be accessed.</li>
5647 </ul></li>
5648
5649<li>Return Value:
5650
5651<ul>
5652
5653<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>
5654
5655<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5656
5657<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5658
5659<li>any other non-interval value will cause a type error.</li>
5660 </ul></li>
5661
5662<li>
5663<p>Example:</p>
5664
5665<div class="source">
5666<div class="source">
5667<pre>{
5668 &quot;start&quot;: get_interval_start(interval_start_from_date(&quot;1984-01-01&quot;, &quot;P1Y&quot;)),
5669 &quot;end&quot;: get_interval_end(interval_start_from_date(&quot;1984-01-01&quot;, &quot;P1Y&quot;))
5670};
5671</pre></div></div></li>
5672</ul>
5673
5674<ul>
5675
5676<li>
5677<p>The expected result is:</p>
5678
5679<div class="source">
5680<div class="source">
5681<pre>{ &quot;start&quot;: date(&quot;1984_01_01&quot;), &quot;end&quot;: date(&quot;1985_01_01&quot;) }
5682</pre></div></div></li>
5683</ul></div>
5684<div class="section">
5685<h3><a name="get_interval_start_dateget_interval_start_datetimeget_interval_start_time_get_interval_end_dateget_interval_end_datetimeget_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>
5686
5687<ul>
5688
5689<li>
5690<p>Syntax:</p>
5691
5692<div class="source">
5693<div class="source">
5694<pre>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)
5695</pre></div></div></li>
5696
5697<li>
5698<p>Gets the start/end of the given interval for the specific date/datetime/time type.</p></li>
5699
5700<li>Arguments:
5701
5702<ul>
5703
5704<li><tt>interval</tt>: the interval to be accessed.</li>
5705 </ul></li>
5706
5707<li>Return Value:
5708
5709<ul>
5710
5711<li>a <tt>time</tt>, <tt>date</tt>, or <tt>datetime</tt> (depending on the function) representing the starting or ending time,</li>
5712
5713<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5714
5715<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5716
5717<li>any other non-interval value will cause a type error.</li>
5718 </ul></li>
5719
5720<li>
5721<p>Example:</p>
5722
5723<div class="source">
5724<div class="source">
5725<pre>{
5726 &quot;start1&quot;: get_interval_start_date(interval_start_from_date(&quot;1984-01-01&quot;, &quot;P1Y&quot;)),
5727 &quot;end1&quot;: get_interval_end_date(interval_start_from_date(&quot;1984-01-01&quot;, &quot;P1Y&quot;)),
5728 &quot;start2&quot;: get_interval_start_datetime(interval_start_from_datetime(&quot;1984-01-01T08:30:00.000&quot;, &quot;P1Y1H&quot;)),
5729 &quot;end2&quot;: get_interval_end_datetime(interval_start_from_datetime(&quot;1984-01-01T08:30:00.000&quot;, &quot;P1Y1H&quot;)),
5730 &quot;start3&quot;: get_interval_start_time(interval_start_from_time(&quot;08:30:00.000&quot;, &quot;P1H&quot;)),
5731 &quot;end3&quot;: get_interval_end_time(interval_start_from_time(&quot;08:30:00.000&quot;, &quot;P1H&quot;))
5732};
5733</pre></div></div></li>
5734</ul>
5735
5736<ul>
5737
5738<li>
5739<p>The expected result is:</p>
5740
5741<div class="source">
5742<div class="source">
5743<pre>{
5744 &quot;start1&quot;: date(&quot;1984-01-01&quot;),
5745 &quot;end1&quot;: date(&quot;1985-01-01&quot;),
5746 &quot;start2&quot;: datetime(&quot;1984-01-01T08:30:00.000Z&quot;),
5747 &quot;end2&quot;: datetime(&quot;1985-01-01T09:30:00.000Z&quot;),
5748 &quot;start3&quot;: time(&quot;08:30:00.000Z&quot;),
5749 &quot;end3&quot;: time(&quot;09:30:00.000Z&quot;)
5750}
5751</pre></div></div></li>
5752</ul></div>
5753<div class="section">
5754<h3><a name="get_overlapping_interval"></a>get_overlapping_interval</h3>
5755
5756<ul>
5757
5758<li>
5759<p>Syntax:</p>
5760
5761<div class="source">
5762<div class="source">
5763<pre>get_overlapping_interval(interval1, interval2)
5764</pre></div></div></li>
5765
5766<li>
5767<p>Gets the start/end of the given interval for the specific date/datetime/time type.</p></li>
5768
5769<li>Arguments:
5770
5771<ul>
5772
5773<li><tt>interval1</tt>: an <tt>interval</tt> value</li>
5774
5775<li><tt>interval2</tt>: an <tt>interval</tt> value</li>
5776 </ul></li>
5777
5778<li>Return Value:
5779
5780<ul>
5781
5782<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>
5783
5784<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
5785
5786<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
5787
5788<li>any other non-interval input value will cause a type error.</li>
5789 </ul></li>
5790
5791<li>
5792<p>Example:</p>
5793
5794<div class="source">
5795<div class="source">
5796<pre>{ &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;))),
5797 &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;))),
5798 &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;))),
5799 &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;))),
5800 &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;))),
5801 &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;)))
5802};
5803</pre></div></div></li>
5804
5805<li>
5806<p>The expected result is:</p>
5807
5808<div class="source">
5809<div class="source">
5810<pre>{ &quot;overlap1&quot;: interval(time(&quot;12:23:39.000Z&quot;), time(&quot;18:27:19.000Z&quot;)),
5811 &quot;overlap2&quot;: null,
5812 &quot;overlap3&quot;: null,
5813 &quot;overlap4&quot;: interval(date(&quot;2013-01-01&quot;), date(&quot;2014_01_01&quot;)),
5814 &quot;overlap5&quot;: interval(datetime(&quot;1989-03-04T12:23:39.000Z&quot;), datetime(&quot;2000-10-30T18:27:19.000Z&quot;)),
5815 &quot;overlap6&quot;: null
5816}
5817</pre></div></div></li>
5818</ul></div>
5819<div class="section">
5820<h3><a name="interval_bin"></a>interval_bin</h3>
5821
5822<ul>
5823
5824<li>
5825<p>Syntax:</p>
5826
5827<div class="source">
5828<div class="source">
5829<pre>interval_bin(time_to_bin, time_bin_anchor, duration_bin_size)
5830</pre></div></div></li>
5831
5832<li>
5833<p>Returns the <tt>interval</tt> value representing the bin containing the <tt>time_to_bin</tt> value.</p></li>
5834
5835<li>Arguments:
5836
5837<ul>
5838
5839<li><tt>time_to_bin</tt>: a date/time/datetime value representing the time to be binned.</li>
5840
5841<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>
5842
5843<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:
5844
5845<ul>
5846
5847<li>datetime +|_ year_month_duration</li>
5848
5849<li>datetime +|_ day_time_duration</li>
5850
5851<li>date +|_ year_month_duration</li>
5852
5853<li>date +|_ day_time_duration</li>
5854
5855<li>time +|_ day_time_duration</li>
5856 </ul></li>
5857 </ul></li>
5858
5859<li>Return Value:
5860
5861<ul>
5862
5863<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>
5864
5865<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
5866
5867<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
5868
5869<li>a type error will be raised if:
5870
5871<ul>
5872
5873<li>the first argument or the second argument is any other non-date/non-time/non-datetime value,</li>
5874
5875<li>or, the second argument is any other non-year_month_duration/non-day_time_duration value.</li>
5876 </ul></li>
5877 </ul></li>
5878
5879<li>
5880<p>Example:</p>
5881
5882<div class="source">
5883<div class="source">
5884<pre>{
5885 &quot;bin1&quot;: interval_bin(date(&quot;2010-10-30&quot;), date(&quot;1990-01-01&quot;), year_month_duration(&quot;P1Y&quot;)),
5886 &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;)),
5887 &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;)),
5888 &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;))
5889};
5890</pre></div></div></li>
5891
5892<li>
5893<p>The expected result is:</p>
5894
5895<div class="source">
5896<div class="source">
5897<pre>{
5898 &quot;bin1&quot;: interval(date(&quot;2010-01-01&quot;),date(&quot;2011-01-01&quot;)),
5899 &quot;bin2&quot;: interval(datetime(&quot;1987-07-01T00:00:00.000Z&quot;), datetime(&quot;1988-01-01T00:00:00.000Z&quot;)),
5900 &quot;bin3&quot;: interval(time(&quot;05:23:00.000Z&quot;), time(&quot;05:24:00.000Z&quot;)),
5901 &quot;bin4&quot;: interval(datetime(&quot;1987-11-19T00:00:00.000Z&quot;), datetime(&quot;1987-11-20T00:00:00.000Z&quot;))
5902}
5903</pre></div></div></li>
5904</ul></div>
5905<div class="section">
5906<h3><a name="interval_start_from_datetimedatetime"></a>interval_start_from_date/time/datetime</h3>
5907
5908<ul>
5909
5910<li>
5911<p>Syntax:</p>
5912
5913<div class="source">
5914<div class="source">
5915<pre>interval_start_from_date/time/datetime(date/time/datetime, duration)
5916</pre></div></div></li>
5917
5918<li>
5919<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></li>
5920
5921<li>Arguments:
5922
5923<ul>
5924
5925<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>
5926
5927<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>
5928 </ul></li>
5929
5930<li>Return Value:
5931
5932<ul>
5933
5934<li>an <tt>interval</tt> value representing the interval starting from the given time point with the length of duration,</li>
5935
5936<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
5937
5938<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
5939
5940<li>a type error will be raised if:
5941
5942<ul>
5943
5944<li>the first argument or the second argument is any other non-date/non-time/non-datetime value,</li>
5945
5946<li>or, the second argument is any other non-duration value.</li>
5947 </ul></li>
5948 </ul></li>
5949
5950<li>
5951<p>Example:</p>
5952
5953<div class="source">
5954<div class="source">
5955<pre>{
5956 &quot;interval1&quot;: interval_start_from_date(&quot;1984-01-01&quot;, &quot;P1Y&quot;),
5957 &quot;interval2&quot;: interval_start_from_time(time(&quot;02:23:28.394&quot;), &quot;PT3H24M&quot;),
5958 &quot;interval3&quot;: interval_start_from_datetime(&quot;1999-09-09T09:09:09.999&quot;, duration(&quot;P2M30D&quot;))
5959};
5960</pre></div></div></li>
5961
5962<li>
5963<p>The expectecd result is:</p>
5964
5965<div class="source">
5966<div class="source">
5967<pre>{
5968 &quot;interval1&quot;: interval(date(&quot;1984-01-01&quot;), date(&quot;1985-01-01&quot;)),
5969 &quot;interval2&quot;: interval(time(&quot;02:23:28.394Z&quot;), time(&quot;05:47:28.394Z&quot;)),
5970 &quot;interval3&quot;: interval(datetime(&quot;1999-09-09T09:09:09.999Z&quot;), datetime(&quot;1999-12-09T09:09:09.999Z&quot;))
5971}
5972</pre></div></div></li>
5973</ul></div>
5974<div class="section">
5975<h3><a name="overlap_bins"></a>overlap_bins</h3>
5976
5977<ul>
5978
5979<li>
5980<p>Return Value:</p>
5981
5982<ul>
5983
5984<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>
5985 </ul></li>
5986
5987<li>
5988<p>Syntax:</p>
5989
5990<div class="source">
5991<div class="source">
5992<pre>overlap_bins(interval, time_bin_anchor, duration_bin_size)
5993</pre></div></div></li>
5994
5995<li>
5996<p>Returns an ordered list of <tt>interval</tt> values representing each bin that is overlapping the <tt>interval</tt>.</p></li>
5997
5998<li>Arguments:
5999
6000<ul>
6001
6002<li><tt>interval</tt>: an <tt>interval</tt> value</li>
6003
6004<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>
6005
6006<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:
6007
6008<ul>
6009
6010<li>datetime +|_ year_month_duration</li>
6011
6012<li>datetime +|_ day_time_duration</li>
6013
6014<li>date +|_ year_month_duration</li>
6015
6016<li>date +|_ day_time_duration</li>
6017
6018<li>time +|_ day_time_duration</li>
6019 </ul></li>
6020 </ul></li>
6021
6022<li>Return Value:
6023
6024<ul>
6025
6026<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>
6027
6028<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
6029
6030<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6031
6032<li>a type error will be raised if:
6033
6034<ul>
6035
6036<li>the first arugment is any other non-interval value,</li>
6037
6038<li>or, the second argument is any other non-date/non-time/non-datetime value,</li>
6039
6040<li>or, the second argument is any other non-year_month_duration/non-day_time_duration value.</li>
6041 </ul></li>
6042 </ul></li>
6043
6044<li>
6045<p>Example:</p>
6046
6047<div class="source">
6048<div class="source">
6049<pre>{
6050 &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;)),
6051 &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;)),
6052 &quot;datetimebins&quot;: overlap_bins(interval(datetime(&quot;1800-01-01T23:59:48.938&quot;), datetime(&quot;2015-07-26T13:28:30.218&quot;)),
6053 datetime(&quot;1900-01-01T00:00:00.000&quot;), year_month_duration(&quot;P100Y&quot;))
6054};
6055</pre></div></div></li>
6056
6057<li>
6058<p>The expected result is:</p>
6059
6060<div class="source">
6061<div class="source">
6062<pre>{
6063 &quot;timebins&quot;: [
6064 interval(time(&quot;17:00:00.000Z&quot;), time(&quot;17:30:00.000Z&quot;)),
6065 interval(time(&quot;17:30:00.000Z&quot;), time(&quot;18:00:00.000Z&quot;)),
6066 interval(time(&quot;18:00:00.000Z&quot;), time(&quot;18:30:00.000Z&quot;)),
6067 interval(time(&quot;18:30:00.000Z&quot;), time(&quot;19:00:00.000Z&quot;))
6068 ],
6069 &quot;datebins&quot;: [
6070 interval(date(&quot;1980-01-01&quot;), date(&quot;1990-01-01&quot;)),
6071 interval(date(&quot;1990-01-01&quot;), date(&quot;2000-01-01&quot;)),
6072 interval(date(&quot;2000-01-01&quot;), date(&quot;2010-01-01&quot;)),
6073 interval(date(&quot;2010-01-01&quot;), date(&quot;2020-01-01&quot;))
6074 ],
6075 &quot;datetimebins&quot;: [
6076 interval(datetime(&quot;1800-01-01T00:00:00.000Z&quot;), datetime(&quot;1900-01-01T00:00:00.000Z&quot;)),
6077 interval(datetime(&quot;1900-01-01T00:00:00.000Z&quot;), datetime(&quot;2000-01-01T00:00:00.000Z&quot;)),
6078 interval(datetime(&quot;2000-01-01T00:00:00.000Z&quot;), datetime(&quot;2100-01-01T00:00:00.000Z&quot;))
6079 ]
6080};
6081</pre></div></div></li>
6082</ul>
6083<!-- ! Licensed to the Apache Software Foundation (ASF) under one
6084 ! or more contributor license agreements. See the NOTICE file
6085 ! distributed with this work for additional information
6086 ! regarding copyright ownership. The ASF licenses this file
6087 ! to you under the Apache License, Version 2.0 (the
6088 ! "License"); you may not use this file except in compliance
6089 ! with the License. You may obtain a copy of the License at
6090 !
6091 ! http://www.apache.org/licenses/LICENSE-2.0
6092 !
6093 ! Unless required by applicable law or agreed to in writing,
6094 ! software distributed under the License is distributed on an
6095 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
6096 ! KIND, either express or implied. See the License for the
6097 ! specific language governing permissions and limitations
6098 ! under the License.
6099 ! --></div>
6100<div class="section">
6101<h3><a name="interval_before_interval_after"></a>interval_before, interval_after</h3>
6102
6103<ul>
6104
6105<li>
6106<p>Syntax:</p>
6107
6108<div class="source">
6109<div class="source">
6110<pre>interval_before(interval1, interval2)
6111interval_after(interval1, interval2)
6112</pre></div></div></li>
6113
6114<li>
6115<p>These two functions check whether an interval happens before/after another interval.</p></li>
6116
6117<li>Arguments:
6118
6119<ul>
6120
6121<li><tt>interval1</tt>, <tt>interval2</tt>: two intervals to be compared</li>
6122 </ul></li>
6123
6124<li>Return Value:
6125
6126<ul>
6127
6128<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>
6129
6130<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
6131
6132<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6133
6134<li>any other non-interval input value will cause a type error.</li>
6135 </ul></li>
6136
6137<li>
6138<p>Examples:</p>
6139
6140<div class="source">
6141<div class="source">
6142<pre>{
6143 &quot;interval_before&quot;: interval_before(interval(date(&quot;2000-01-01&quot;), date(&quot;2005-01-01&quot;)),
6144 interval(date(&quot;2005-05-01&quot;), date(&quot;2012-09-09&quot;))),
6145 &quot;interval_after&quot;: interval_after(interval(date(&quot;2005-05-01&quot;), date(&quot;2012-09-09&quot;)),
6146 interval(date(&quot;2000-01-01&quot;), date(&quot;2005-01-01&quot;)))
6147};
6148</pre></div></div></li>
6149
6150<li>
6151<p>The expected result is:</p>
6152
6153<div class="source">
6154<div class="source">
6155<pre>{ &quot;interval_before&quot;: true, &quot;interval_after&quot;: true }
6156</pre></div></div></li>
6157</ul></div>
6158<div class="section">
6159<h3><a name="interval_covers_interval_covered_by"></a>interval_covers, interval_covered_by</h3>
6160
6161<ul>
6162
6163<li>
6164<p>Syntax:</p>
6165
6166<div class="source">
6167<div class="source">
6168<pre>interval_covers(interval1, interval2)
6169interval_covered_by(interval1, interval2)
6170</pre></div></div></li>
6171
6172<li>
6173<p>These two functions check whether one interval covers the other interval.</p></li>
6174
6175<li>Arguments:
6176
6177<ul>
6178
6179<li><tt>interval1</tt>, <tt>interval2</tt>: two intervals to be compared</li>
6180 </ul></li>
6181
6182<li>
6183<p>Return Value:</p>
6184
6185<ul>
6186
6187<li>a <tt>boolean</tt> value. Specifically, <tt>interval_covers(interval1, interval2)</tt> is true if and only if</li>
6188 </ul>
6189
6190<div class="source">
6191<div class="source">
6192<pre>interval1.start &lt;= interval2.start AND interval1.end &gt;= interval2.end
6193
6194`interval_covered_by(interval1, interval2)` is true if and only if
6195
6196interval2.start &lt;= interval1.start AND interval2.end &gt;= interval1.end
6197</pre></div></div>
6198
6199<ul>
6200
6201<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
6202
6203<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6204
6205<li>any other non-interval input value will cause a type error.</li>
6206 </ul></li>
6207
6208<li>
6209<p>Examples:</p>
6210
6211<div class="source">
6212<div class="source">
6213<pre>{
6214 &quot;interval_covers&quot;: interval_covers(interval(date(&quot;2000-01-01&quot;), date(&quot;2005-01-01&quot;)),
6215 interval(date(&quot;2000-03-01&quot;), date(&quot;2004-09-09&quot;))),
6216 &quot;interval_covered_by&quot;: interval_covered_by(interval(date(&quot;2006-08-01&quot;), date(&quot;2007-03-01&quot;)),
6217 interval(date(&quot;2004-09-10&quot;), date(&quot;2012-08-01&quot;)))
6218};
6219</pre></div></div></li>
6220
6221<li>
6222<p>The expected result is:</p>
6223
6224<div class="source">
6225<div class="source">
6226<pre>{ &quot;interval_covers&quot;: true, &quot;interval_covered_by&quot;: true }
6227</pre></div></div></li>
6228</ul></div>
6229<div class="section">
6230<h3><a name="interval_overlaps_interval_overlapped_by"></a>interval_overlaps, interval_overlapped_by</h3>
6231
6232<ul>
6233
6234<li>
6235<p>Syntax:</p>
6236
6237<div class="source">
6238<div class="source">
6239<pre>interval_overlaps(interval1, interval2)
6240interval_overlapped_by(interval1, interval2)
6241</pre></div></div></li>
6242
6243<li>
6244<p>These functions check whether two intervals overlap with each other.</p></li>
6245
6246<li>Arguments:
6247
6248<ul>
6249
6250<li><tt>interval1</tt>, <tt>interval2</tt>: two intervals to be compared</li>
6251 </ul></li>
6252
6253<li>
6254<p>Return Value:</p>
6255
6256<ul>
6257
6258<li>a <tt>boolean</tt> value. Specifically, <tt>interval_overlaps(interval1, interval2)</tt> is true if and only if</li>
6259 </ul>
6260
6261<div class="source">
6262<div class="source">
6263<pre>interval1.start &lt; interval2.start
6264AND interval2.end &gt; interval1.end
6265AND interval1.end &gt; interval2.start
6266</pre></div></div>
6267<p><tt>interval_overlapped_by(interval1, interval2)</tt> is true if and only if</p>
6268
6269<div class="source">
6270<div class="source">
6271<pre>interval2.start &lt; interval1.start
6272AND interval1.end &gt; interval2.end
6273AND interval2.end &gt; interval1.start
6274</pre></div></div>
6275
6276<ul>
6277
6278<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
6279
6280<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6281
6282<li>any other non-interval input value will cause a type error.</li>
6283 </ul>
6284<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></li>
6285
6286<li>
6287<p>Examples:</p>
6288
6289<div class="source">
6290<div class="source">
6291<pre>{
6292 &quot;overlaps&quot;: interval_overlaps(interval(date(&quot;2000-01-01&quot;), date(&quot;2005-01-01&quot;)),
6293 interval(date(&quot;2004-05-01&quot;), date(&quot;2012-09-09&quot;))),
6294 &quot;overlapped_by&quot;: interval_overlapped_by(interval(date(&quot;2006-08-01&quot;), date(&quot;2007-03-01&quot;)),
6295 interval(date(&quot;2004-05-01&quot;), date(&quot;2012-09-09&quot;))))
6296};
6297</pre></div></div></li>
6298
6299<li>
6300<p>The expected result is:</p>
6301
6302<div class="source">
6303<div class="source">
6304<pre>{ &quot;overlaps&quot;: true, &quot;overlapped_by&quot;: true }
6305</pre></div></div></li>
6306</ul></div>
6307<div class="section">
6308<h3><a name="interval_overlapping"></a>interval_overlapping</h3>
6309<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>
6310
6311<ul>
6312
6313<li>
6314<p>Syntax:</p>
6315
6316<div class="source">
6317<div class="source">
6318<pre>interval_overlapping(interval1, interval2)
6319</pre></div></div></li>
6320
6321<li>
6322<p>This functions check whether two intervals share any points with each other.</p></li>
6323
6324<li>Arguments:
6325
6326<ul>
6327
6328<li><tt>interval1</tt>, <tt>interval2</tt>: two intervals to be compared</li>
6329 </ul></li>
6330
6331<li>
6332<p>Return Value:</p>
6333
6334<ul>
6335
6336<li>a <tt>boolean</tt> value. Specifically, <tt>interval_overlapping(interval1, interval2)</tt> is true if</li>
6337 </ul>
6338
6339<div class="source">
6340<div class="source">
6341<pre>interval1.start &lt; interval2.end
6342AND interval1.end &gt; interval2.start
6343</pre></div></div>
6344
6345<ul>
6346
6347<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
6348
6349<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6350
6351<li>any other non-interval input value will cause a type error.</li>
6352 </ul></li>
6353
6354<li>
6355<p>Examples:</p>
6356
6357<div class="source">
6358<div class="source">
6359<pre>{
6360 &quot;overlapping1&quot;: interval_overlapping(interval(date(&quot;2000-01-01&quot;), date(&quot;2005-01-01&quot;)),
6361 interval(date(&quot;2004-05-01&quot;), date(&quot;2012-09-09&quot;))),
6362 &quot;overlapping2&quot;: interval_overlapping(interval(date(&quot;2006-08-01&quot;), date(&quot;2007-03-01&quot;)),
6363 interval(date(&quot;2004-09-10&quot;), date(&quot;2006-12-31&quot;)))
6364};
6365</pre></div></div></li>
6366
6367<li>
6368<p>The expected result is:</p>
6369
6370<div class="source">
6371<div class="source">
6372<pre>{ &quot;overlapping1&quot;: true, &quot;overlapping2&quot;: true }
6373</pre></div></div></li>
6374</ul></div>
6375<div class="section">
6376<h3><a name="interval_meets_interval_met_by"></a>interval_meets, interval_met_by</h3>
6377
6378<ul>
6379
6380<li>
6381<p>Syntax:</p>
6382
6383<div class="source">
6384<div class="source">
6385<pre>interval_meets(interval1, interval2)
6386interval_met_by(interval1, interval2)
6387</pre></div></div></li>
6388
6389<li>
6390<p>These two functions check whether an interval meets with another interval.</p></li>
6391
6392<li>Arguments:
6393
6394<ul>
6395
6396<li><tt>interval1</tt>, <tt>interval2</tt>: two intervals to be compared</li>
6397 </ul></li>
6398
6399<li>Return Value:
6400
6401<ul>
6402
6403<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>
6404
6405<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
6406
6407<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6408
6409<li>any other non-interval input value will cause a type error.</li>
6410 </ul></li>
6411
6412<li>
6413<p>Examples:</p>
6414
6415<div class="source">
6416<div class="source">
6417<pre>{
6418 &quot;meets&quot;: interval_meets(interval(date(&quot;2000-01-01&quot;), date(&quot;2005-01-01&quot;)),
6419 interval(date(&quot;2005-01-01&quot;), date(&quot;2012-09-09&quot;))),
6420 &quot;metby&quot;: interval_met_by(interval(date(&quot;2006-08-01&quot;), date(&quot;2007-03-01&quot;)),
6421 interval(date(&quot;2004-09-10&quot;), date(&quot;2006-08-01&quot;)))
6422};
6423</pre></div></div></li>
6424
6425<li>
6426<p>The expected result is:</p>
6427
6428<div class="source">
6429<div class="source">
6430<pre>{ &quot;meets&quot;: true, &quot;metby&quot;: true }
6431</pre></div></div></li>
6432</ul></div>
6433<div class="section">
6434<h3><a name="interval_starts_interval_started_by"></a>interval_starts, interval_started_by</h3>
6435
6436<ul>
6437
6438<li>
6439<p>Syntax:</p>
6440
6441<div class="source">
6442<div class="source">
6443<pre>interval_starts(interval1, interval2)
6444interval_started_by(interval1, interval2)
6445</pre></div></div></li>
6446
6447<li>
6448<p>These two functions check whether one interval starts with the other interval.</p></li>
6449
6450<li>Arguments:
6451
6452<ul>
6453
6454<li><tt>interval1</tt>, <tt>interval2</tt>: two intervals to be compared</li>
6455 </ul></li>
6456
6457<li>
6458<p>Return Value:</p>
6459
6460<ul>
6461
6462<li>a <tt>boolean</tt> value. Specifically, <tt>interval_starts(interval1, interval2)</tt> returns true if and only if</li>
6463 </ul>
6464
6465<div class="source">
6466<div class="source">
6467<pre>interval1.start = interval2.start
6468AND interval1.end &lt;= interval2.end
6469</pre></div></div>
6470<p><tt>interval_started_by(interval1, interval2)</tt> returns true if and only if</p>
6471
6472<div class="source">
6473<div class="source">
6474<pre>interval1.start = interval2.start
6475AND interval2.end &lt;= interval1.end
6476</pre></div></div>
6477
6478<ul>
6479
6480<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
6481
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
6484<li>any other non-interval input value will cause a type error.</li>
6485 </ul></li>
6486
6487<li>
6488<p>Examples:</p>
6489
6490<div class="source">
6491<div class="source">
6492<pre>{
6493 &quot;interval_starts&quot;: interval_starts(interval(date(&quot;2000-01-01&quot;), date(&quot;2005-01-01&quot;)),
6494 interval(date(&quot;2000-01-01&quot;), date(&quot;2012-09-09&quot;))),
6495 &quot;interval_started_by&quot;: interval_started_by(interval(date(&quot;2006-08-01&quot;), date(&quot;2007-03-01&quot;)),
6496 interval(date(&quot;2006-08-01&quot;), date(&quot;2006-08-02&quot;)))
6497};
6498</pre></div></div></li>
6499
6500<li>
6501<p>The expected result is:</p>
6502
6503<div class="source">
6504<div class="source">
6505<pre>{ &quot;interval_starts&quot;: true, &quot;interval_started_by&quot;: true }
6506</pre></div></div></li>
6507</ul></div>
6508<div class="section">
6509<h3><a name="interval_ends_interval_ended_by"></a>interval_ends, interval_ended_by</h3>
6510
6511<ul>
6512
6513<li>
6514<p>Syntax:</p>
6515
6516<div class="source">
6517<div class="source">
6518<pre>interval_ends(interval1, interval2)
6519interval_ended_by(interval1, interval2)
6520</pre></div></div></li>
6521
6522<li>
6523<p>These two functions check whether one interval ends with the other interval.</p></li>
6524
6525<li>Arguments:
6526
6527<ul>
6528
6529<li><tt>interval1</tt>, <tt>interval2</tt>: two intervals to be compared</li>
6530 </ul></li>
6531
6532<li>
6533<p>Return Value:</p>
6534
6535<ul>
6536
6537<li>a <tt>boolean</tt> value. Specifically, <tt>interval_ends(interval1, interval2)</tt> returns true if and only if</li>
6538 </ul>
6539
6540<div class="source">
6541<div class="source">
6542<pre>interval1.end = interval2.end
6543AND interval1.start &gt;= interval2.start
6544
6545`interval_ended_by(interval1, interval2)` returns true if and only if
6546
6547interval2.end = interval1.end
6548AND interval2.start &gt;= interval1.start
6549</pre></div></div>
6550
6551<ul>
6552
6553<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
6554
6555<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6556
6557<li>any other non-interval input value will cause a type error.</li>
6558 </ul></li>
6559
6560<li>
6561<p>Examples:</p>
6562
6563<div class="source">
6564<div class="source">
6565<pre>{
6566 &quot;interval_ends&quot;: interval_ends(interval(date(&quot;2000-01-01&quot;), date(&quot;2005-01-01&quot;)),
6567 interval(date(&quot;1998-01-01&quot;), date(&quot;2005-01-01&quot;))),
6568 &quot;interval_ended_by&quot;: interval_ended_by(interval(date(&quot;2006-08-01&quot;), date(&quot;2007-03-01&quot;)),
6569 interval(date(&quot;2006-09-10&quot;), date(&quot;2007-03-01&quot;)))
6570};
6571</pre></div></div></li>
6572
6573<li>
6574<p>The expected result is:</p>
6575
6576<div class="source">
6577<div class="source">
6578<pre>{ &quot;interval_ends&quot;: true, &quot;interval_ended_by&quot;: true }
6579</pre></div></div></li>
6580</ul>
6581<!-- ! Licensed to the Apache Software Foundation (ASF) under one
6582 ! or more contributor license agreements. See the NOTICE file
6583 ! distributed with this work for additional information
6584 ! regarding copyright ownership. The ASF licenses this file
6585 ! to you under the Apache License, Version 2.0 (the
6586 ! "License"); you may not use this file except in compliance
6587 ! with the License. You may obtain a copy of the License at
6588 !
6589 ! http://www.apache.org/licenses/LICENSE-2.0
6590 !
6591 ! Unless required by applicable law or agreed to in writing,
6592 ! software distributed under the License is distributed on an
6593 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
6594 ! KIND, either express or implied. See the License for the
6595 ! specific language governing permissions and limitations
6596 ! under the License.
6597 ! --></div></div>
6598<div class="section">
6599<h2><a name="Object_Functions"></a><a name="ObjectFunctions" id="ObjectFunctions">Object Functions</a></h2>
6600<div class="section">
6601<h3><a name="get_object_fields"></a>get_object_fields</h3>
6602
6603<ul>
6604
6605<li>
6606<p>Syntax:</p>
6607
6608<div class="source">
6609<div class="source">
6610<pre>get_object_fields(input_object)
6611</pre></div></div></li>
6612
6613<li>
6614<p>Access the object field names, type and open status for a given object.</p></li>
6615
6616<li>Arguments:
6617
6618<ul>
6619
6620<li><tt>input_object</tt> : a object value.</li>
6621 </ul></li>
6622
6623<li>Return Value:
6624
6625<ul>
6626
6627<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>
6628
6629<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
6630
6631<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
6632
6633<li>any other non-object input value will cause a type error.</li>
6634 </ul></li>
6635
6636<li>
6637<p>Example:</p>
6638
6639<div class="source">
6640<div class="source">
6641<pre>get_object_fields(
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 &quot;related&quot;: [&quot;Hivestrix&quot;, &quot;Preglix&quot;, &quot;Apache VXQuery&quot;]
6647 }
6648 );
6649</pre></div></div></li>
6650
6651<li>
6652<p>The expected result is:</p>
6653
6654<div class="source">
6655<div class="source">
6656<pre>[
6657 { &quot;field-name&quot;: &quot;id&quot;, &quot;field-type&quot;: &quot;INT64&quot;, &quot;is-open&quot;: false },
6658 { &quot;field-name&quot;: &quot;project&quot;, &quot;field-type&quot;: &quot;STRING&quot;, &quot;is-open&quot;: false },
6659 { &quot;field-name&quot;: &quot;address&quot;, &quot;field-type&quot;: &quot;RECORD&quot;, &quot;is-open&quot;: false,
6660 &quot;nested&quot;: [
6661 { &quot;field-name&quot;: &quot;city&quot;, &quot;field-type&quot;: &quot;STRING&quot;, &quot;is-open&quot;: false },
6662 { &quot;field-name&quot;: &quot;state&quot;, &quot;field-type&quot;: &quot;STRING&quot;, &quot;is-open&quot;: false }
6663 ]
6664 },
6665 { &quot;field-name&quot;:
6666 &quot;related&quot;,
6667 &quot;field-type&quot;: &quot;ORDEREDLIST&quot;,
6668 &quot;is-open&quot;: false,
6669 &quot;list&quot;: [
6670 { &quot;field-type&quot;: &quot;STRING&quot; },
6671 { &quot;field-type&quot;: &quot;STRING&quot; },
6672 { &quot;field-type&quot;: &quot;STRING&quot; }
6673 ]
6674 }
6675]
6676</pre></div></div></li>
6677</ul>
6678<p>]</p></div>
6679<div class="section">
6680<h3><a name="get_object_field_value"></a>get_object_field_value</h3>
6681
6682<ul>
6683
6684<li>
6685<p>Syntax:</p>
6686
6687<div class="source">
6688<div class="source">
6689<pre>get_object_field_value(input_object, string)
6690</pre></div></div></li>
6691
6692<li>
6693<p>Access the field name given in the <tt>string_expression</tt> from the <tt>object_expression</tt>.</p></li>
6694
6695<li>Arguments:
6696
6697<ul>
6698
6699<li><tt>input_object</tt> : a <tt>object</tt> value.</li>
6700
6701<li><tt>string</tt> : a <tt>string</tt> representing the top level field name.</li>
6702 </ul></li>
6703
6704<li>Return Value:
6705
6706<ul>
6707
6708<li>an <tt>any</tt> value saved in the designated field of the object,</li>
6709
6710<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
6711
6712<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6713
6714<li>a type error will be raised if:
6715
6716<ul>
6717
6718<li>the first argument is any other non-object value,</li>
6719
6720<li>or, the second argument is any other non-string value.</li>
6721 </ul></li>
6722 </ul></li>
6723
6724<li>
6725<p>Example:</p>
6726
6727<div class="source">
6728<div class="source">
6729<pre>get_object_field_value({
6730 &quot;id&quot;: 1,
6731 &quot;project&quot;: &quot;AsterixDB&quot;,
6732 &quot;address&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;},
6733 &quot;related&quot;: [&quot;Hivestrix&quot;, &quot;Preglix&quot;, &quot;Apache VXQuery&quot;]
6734 },
6735 &quot;project&quot;
6736 );
6737</pre></div></div></li>
6738
6739<li>
6740<p>The expected result is:</p>
6741
6742<div class="source">
6743<div class="source">
6744<pre>&quot;AsterixDB&quot;
6745</pre></div></div></li>
6746</ul></div>
6747<div class="section">
6748<h3><a name="object_remove_fields"></a>object_remove_fields</h3>
6749
6750<ul>
6751
6752<li>
6753<p>Syntax:</p>
6754
6755<div class="source">
6756<div class="source">
6757<pre>object_remove_fields(input_object, field_names)
6758</pre></div></div></li>
6759
6760<li>
6761<p>Remove indicated fields from a object given a list of field names.</p></li>
6762
6763<li>Arguments:
6764
6765<ul>
6766
6767<li><tt>input_object</tt>: a object value.</li>
6768
6769<li><tt>field_names</tt>: an array of strings and/or array of array of strings.</li>
6770 </ul></li>
6771
6772<li>
6773<p>Return Value:</p>
6774
6775<ul>
6776
6777<li>a new object value without the fields listed in the second argument,</li>
6778
6779<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
6780
6781<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6782
6783<li>a type error will be raised if:
6784
6785<ul>
6786
6787<li>the first argument is any other non-object value,</li>
6788
6789<li>or, the second argument is any other non-array value or recursively contains non-string items.</li>
6790 </ul></li>
6791 </ul></li>
6792</ul>
6793
6794<ul>
6795
6796<li>
6797<p>Example:</p>
6798
6799<div class="source">
6800<div class="source">
6801<pre>object_remove_fields(
6802 {
6803 &quot;id&quot;:1,
6804 &quot;project&quot;:&quot;AsterixDB&quot;,
6805 &quot;address&quot;:{&quot;city&quot;:&quot;Irvine&quot;, &quot;state&quot;:&quot;CA&quot;},
6806 &quot;related&quot;:[&quot;Hivestrix&quot;, &quot;Preglix&quot;, &quot;Apache VXQuery&quot;]
6807 },
6808 [[&quot;address&quot;, &quot;city&quot;], &quot;related&quot;]
6809 );
6810</pre></div></div></li>
6811
6812<li>
6813<p>The expected result is:</p>
6814
6815<div class="source">
6816<div class="source">
6817<pre>{
6818 &quot;id&quot;:1,
6819 &quot;project&quot;:&quot;AsterixDB&quot;,
6820 &quot;address&quot;:{ &quot;state&quot;: &quot;CA&quot; }
6821}
6822</pre></div></div></li>
6823</ul></div>
6824<div class="section">
6825<h3><a name="object_add_fields"></a>object_add_fields</h3>
6826
6827<ul>
6828
6829<li>
6830<p>Syntax:</p>
6831
6832<div class="source">
6833<div class="source">
6834<pre>object_add_fields(input_object, fields)
6835</pre></div></div></li>
6836
6837<li>
6838<p>Add fields to a object given a list of field names.</p></li>
6839
6840<li>Arguments:
6841
6842<ul>
6843
6844<li><tt>input_object</tt> : a object value.</li>
6845
6846<li><tt>fields</tt>: an array of field descriptor objects where each object has field_name and field_value.</li>
6847 </ul></li>
6848
6849<li>Return Value:
6850
6851<ul>
6852
6853<li>a new object value with the new fields included,</li>
6854
6855<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
6856
6857<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6858
6859<li>a type error will be raised if:
6860
6861<ul>
6862
6863<li>the first argument is any other non-object value,</li>
6864
6865<li>the second argument is any other non-array value, or contains non-object items.</li>
6866 </ul></li>
6867 </ul></li>
6868</ul>
6869
6870<ul>
6871
6872<li>
6873<p>Example:</p>
6874
6875<div class="source">
6876<div class="source">
6877<pre>object_add_fields(
6878 {
6879 &quot;id&quot;:1,
6880 &quot;project&quot;:&quot;AsterixDB&quot;,
6881 &quot;address&quot;:{&quot;city&quot;:&quot;Irvine&quot;, &quot;state&quot;:&quot;CA&quot;},
6882 &quot;related&quot;:[&quot;Hivestrix&quot;, &quot;Preglix&quot;, &quot;Apache VXQuery&quot;]
6883 },
6884 [{&quot;field-name&quot;:&quot;employment_location&quot;, &quot;field-value&quot;:create_point(30.0,70.0)}]
6885 );
6886</pre></div></div></li>
6887
6888<li>
6889<p>The expected result is:</p>
6890
6891<div class="source">
6892<div class="source">
6893<pre>{
6894 &quot;id&quot;:1,
6895 &quot;project&quot;:&quot;AsterixDB&quot;,
6896 &quot;address&quot;:{&quot;city&quot;:&quot;Irvine&quot;, &quot;state&quot;:&quot;CA&quot;},
6897 &quot;related&quot;:[&quot;Hivestrix&quot;, &quot;Preglix&quot;, &quot;Apache VXQuery&quot;]
6898 &quot;employment_location&quot;: point(&quot;30.0,70.0&quot;)
6899 }
6900</pre></div></div></li>
6901</ul></div>
6902<div class="section">
6903<h3><a name="object_merge"></a>object_merge</h3>
6904
6905<ul>
6906
6907<li>
6908<p>Syntax:</p>
6909
6910<div class="source">
6911<div class="source">
6912<pre>object_merge(object1, object2)
6913</pre></div></div></li>
6914
6915<li>
6916<p>Merge two different objects into a new object.</p></li>
6917
6918<li>Arguments:
6919
6920<ul>
6921
6922<li><tt>object1</tt> : a object value.</li>
6923
6924<li><tt>object2</tt> : a object value.</li>
6925 </ul></li>
6926
6927<li>Return Value:
6928
6929<ul>
6930
6931<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>
6932
6933<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
6934
6935<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6936
6937<li>any other non-object input value will cause a type error.</li>
6938 </ul></li>
6939</ul>
6940
6941<ul>
6942
6943<li>
6944<p>Example:</p>
6945
6946<div class="source">
6947<div class="source">
6948<pre>object_merge(
6949 {
6950 &quot;id&quot;:1,
6951 &quot;project&quot;:&quot;AsterixDB&quot;,
6952 &quot;address&quot;:{&quot;city&quot;:&quot;Irvine&quot;, &quot;state&quot;:&quot;CA&quot;},
6953 &quot;related&quot;:[&quot;Hivestrix&quot;, &quot;Preglix&quot;, &quot;Apache VXQuery&quot;]
6954 },
6955 {
6956 &quot;user_id&quot;: 22,
6957 &quot;employer&quot;: &quot;UC Irvine&quot;,
6958 &quot;employment_type&quot;: &quot;visitor&quot;
6959 }
6960 );
6961</pre></div></div></li>
6962
6963<li>
6964<p>The expected result is:</p>
6965
6966<div class="source">
6967<div class="source">
6968<pre>{
6969 &quot;employment_type&quot;: &quot;visitor&quot;,
6970 &quot;address&quot;: {
6971 &quot;city&quot;: &quot;Irvine&quot;,
6972 &quot;state&quot;: &quot;CA&quot;
6973 },
6974 &quot;related&quot;: [
6975 &quot;Hivestrix&quot;,
6976 &quot;Preglix&quot;,
6977 &quot;Apache VXQuery&quot;
6978 ],
6979 &quot;user_id&quot;: 22,
6980 &quot;project&quot;: &quot;AsterixDB&quot;,
6981 &quot;employer&quot;: &quot;UC Irvine&quot;,
6982 &quot;id&quot;: 1
6983}
6984</pre></div></div></li>
6985</ul>
6986<!-- ! Licensed to the Apache Software Foundation (ASF) under one
6987 ! or more contributor license agreements. See the NOTICE file
6988 ! distributed with this work for additional information
6989 ! regarding copyright ownership. The ASF licenses this file
6990 ! to you under the Apache License, Version 2.0 (the
6991 ! "License"); you may not use this file except in compliance
6992 ! with the License. You may obtain a copy of the License at
6993 !
6994 ! http://www.apache.org/licenses/LICENSE-2.0
6995 !
6996 ! Unless required by applicable law or agreed to in writing,
6997 ! software distributed under the License is distributed on an
6998 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
6999 ! KIND, either express or implied. See the License for the
7000 ! specific language governing permissions and limitations
7001 ! under the License.
7002 ! --></div></div>
7003<div class="section">
7004<h2><a name="Aggregate_Functions_Array_Functions"></a><a name="AggregateFunctions" id="AggregateFunctions">Aggregate Functions (Array Functions) </a></h2>
7005<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>
7006<div class="section">
7007<h3><a name="array_count"></a>array_count</h3>
7008
7009<ul>
7010
7011<li>
7012<p>Syntax:</p>
7013
7014<div class="source">
7015<div class="source">
7016<pre>array_count(collection)
7017</pre></div></div></li>
7018
7019<li>
7020<p>Gets the number of non-null and non-missing items in the given collection.</p></li>
7021
7022<li>Arguments:
7023
7024<ul>
7025
7026<li><tt>collection</tt> could be:
7027
7028<ul>
7029
7030<li>an <tt>array</tt> or <tt>multiset</tt> to be counted,</li>
7031
7032<li>or, a <tt>null</tt> value,</li>
7033
7034<li>or, a <tt>missing</tt> value.</li>
7035 </ul></li>
7036 </ul></li>
7037
7038<li>Return Value:
7039
7040<ul>
7041
7042<li>a <tt>bigint</tt> value representing the number of non-null and non-missing items in the given collection,</li>
7043
7044<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
7045
7046<li>any other non-array and non-multiset input value will cause an error.</li>
7047 </ul></li>
7048
7049<li>
7050<p>Example:</p>
7051
7052<div class="source">
7053<div class="source">
7054<pre>array_count( ['hello', 'world', 1, 2, 3, null, missing] );
7055</pre></div></div></li>
7056</ul>
7057
7058<ul>
7059
7060<li>
7061<p>The expected result is:</p>
7062
7063<div class="source">
7064<div class="source">
7065<pre>5
7066</pre></div></div></li>
7067</ul></div>
7068<div class="section">
7069<h3><a name="array_avg"></a>array_avg</h3>
7070
7071<ul>
7072
7073<li>
7074<p>Syntax:</p>
7075
7076<div class="source">
7077<div class="source">
7078<pre>array_avg(num_collection)
7079</pre></div></div></li>
7080
7081<li>
7082<p>Gets the average value of the non-null and non-missing numeric items in the given collection.</p></li>
7083
7084<li>Arguments:
7085
7086<ul>
7087
7088<li><tt>num_collection</tt> could be:
7089
7090<ul>
7091
7092<li>an <tt>array</tt> or <tt>multiset</tt> containing numeric values, <tt>null</tt>s or <tt>missing</tt>s,</li>
7093
7094<li>or, a <tt>null</tt> value,</li>
7095
7096<li>or, a <tt>missing</tt> value.</li>
7097 </ul></li>
7098 </ul></li>
7099
7100<li>Return Value:
7101
7102<ul>
7103
7104<li>a <tt>double</tt> value representing the average of the non-null and non-missing numbers in the given collection,</li>
7105
7106<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
7107
7108<li><tt>null</tt> is returned if the given collection does not contain any non-null and non-missing items,</li>
7109
7110<li>any other non-array and non-multiset input value will cause a type error,</li>
7111
7112<li>any other non-numeric value in the input collection will cause a type error.</li>
7113 </ul></li>
7114
7115<li>
7116<p>Example:</p>
7117
7118<div class="source">
7119<div class="source">
7120<pre>array_avg( [1.2, 2.3, 3.4, 0, null] );
7121</pre></div></div></li>
7122
7123<li>
7124<p>The expected result is:</p>
7125
7126<div class="source">
7127<div class="source">
7128<pre>1.725
7129</pre></div></div></li>
7130</ul></div>
7131<div class="section">
7132<h3><a name="array_sum"></a>array_sum</h3>
7133
7134<ul>
7135
7136<li>
7137<p>Syntax:</p>
7138
7139<div class="source">
7140<div class="source">
7141<pre>array_sum(num_collection)
7142</pre></div></div></li>
7143
7144<li>
7145<p>Gets the sum of non-null and non-missing items in the given collection.</p></li>
7146
7147<li>Arguments:
7148
7149<ul>
7150
7151<li><tt>num_collection</tt> could be:
7152
7153<ul>
7154
7155<li>an <tt>array</tt> or <tt>multiset</tt> containing numeric values, <tt>null</tt>s or <tt>missing</tt>s,</li>
7156
7157<li>or, a <tt>null</tt> value,</li>
7158
7159<li>or, a <tt>missing</tt> value.</li>
7160 </ul></li>
7161 </ul></li>
7162
7163<li>Return Value:
7164
7165<ul>
7166
7167<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>
7168
7169<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
7170
7171<li><tt>null</tt> is returned if the given collection does not contain any non-null and non-missing items,</li>
7172
7173<li>any other non-array and non-multiset input value will cause a type error,</li>
7174
7175<li>any other non-numeric value in the input collection will cause a type error.</li>
7176 </ul></li>
7177
7178<li>
7179<p>Example:</p>
7180
7181<div class="source">
7182<div class="source">
7183<pre>array_sum( [1.2, 2.3, 3.4, 0, null, missing] );
7184</pre></div></div></li>
7185
7186<li>
7187<p>The expected result is:</p>
7188
7189<div class="source">
7190<div class="source">
7191<pre>6.9
7192</pre></div></div></li>
7193</ul></div>
7194<div class="section">
7195<h3><a name="array_sql_min"></a>array_sql_min</h3>
7196
7197<ul>
7198
7199<li>
7200<p>Syntax:</p>
7201
7202<div class="source">
7203<div class="source">
7204<pre>array_min(num_collection)
7205</pre></div></div></li>
7206
7207<li>
7208<p>Gets the min value of non-null and non-missing comparable items in the given collection.</p></li>
7209
7210<li>Arguments:
7211
7212<ul>
7213
7214<li><tt>num_collection</tt> could be:
7215
7216<ul>
7217
7218<li>an <tt>array</tt> or <tt>multiset</tt>,</li>
7219
7220<li>or, a <tt>null</tt> value,</li>
7221
7222<li>or, a <tt>missing</tt> value.</li>
7223 </ul></li>
7224 </ul></li>
7225
7226<li>Return Value:
7227
7228<ul>
7229
7230<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>
7231
7232<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
7233
7234<li><tt>null</tt> is returned if the given collection does not contain any non-null and non-missing items,</li>
7235
7236<li>multiple incomparable items in the input array or multiset will cause a type error,</li>
7237
7238<li>any other non-array and non-multiset input value will cause a type error.</li>
7239 </ul></li>
7240
7241<li>
7242<p>Example:</p>
7243
7244<div class="source">
7245<div class="source">
7246<pre>array_min( [1.2, 2.3, 3.4, 0, null, missing] );
7247</pre></div></div></li>
7248
7249<li>
7250<p>The expected result is:</p>
7251
7252<div class="source">
7253<div class="source">
7254<pre>0.0
7255</pre></div></div></li>
7256</ul></div>
7257<div class="section">
7258<h3><a name="array_max"></a>array_max</h3>
7259
7260<ul>
7261
7262<li>
7263<p>Syntax:</p>
7264
7265<div class="source">
7266<div class="source">
7267<pre>array_max(num_collection)
7268</pre></div></div></li>
7269
7270<li>
7271<p>Gets the max value of the non-null and non-missing comparable items in the given collection.</p></li>
7272
7273<li>Arguments:
7274
7275<ul>
7276
7277<li><tt>num_collection</tt> could be:
7278
7279<ul>
7280
7281<li>an <tt>array</tt> or <tt>multiset</tt>,</li>
7282
7283<li>or, a <tt>null</tt> value,</li>
7284
7285<li>or, a <tt>missing</tt> value.</li>
7286 </ul></li>
7287 </ul></li>
7288
7289<li>Return Value:
7290
7291<ul>
7292
7293<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>
7294
7295<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
7296
7297<li><tt>null</tt> is returned if the given collection does not contain any non-null and non-missing items,</li>
7298
7299<li>multiple incomparable items in the input array or multiset will cause a type error,</li>
7300
7301<li>any other non-array and non-multiset input value will cause a type error.</li>
7302 </ul></li>
7303
7304<li>
7305<p>Example:</p>
7306
7307<div class="source">
7308<div class="source">
7309<pre>array_max( [1.2, 2.3, 3.4, 0, null, missing] );
7310</pre></div></div></li>
7311
7312<li>
7313<p>The expected result is:</p>
7314
7315<div class="source">
7316<div class="source">
7317<pre>3.4
7318</pre></div></div></li>
7319</ul></div>
7320<div class="section">
7321<h3><a name="coll_count"></a>coll_count</h3>
7322
7323<ul>
7324
7325<li>
7326<p>Syntax:</p>
7327
7328<div class="source">
7329<div class="source">
7330<pre>coll_count(collection)
7331</pre></div></div></li>
7332
7333<li>
7334<p>Gets the number of items in the given collection.</p></li>
7335
7336<li>Arguments:
7337
7338<ul>
7339
7340<li><tt>collection</tt> could be:
7341
7342<ul>
7343
7344<li>an <tt>array</tt> or <tt>multiset</tt> containing the items to be counted,</li>
7345
7346<li>or a <tt>null</tt> value,</li>
7347
7348<li>or a <tt>missing</tt> value.</li>
7349 </ul></li>
7350 </ul></li>
7351
7352<li>Return Value:
7353
7354<ul>
7355
7356<li>a <tt>bigint</tt> value representing the number of items in the given collection,</li>
7357
7358<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>.</li>
7359 </ul></li>
7360
7361<li>
7362<p>Example:</p>
7363
7364<div class="source">
7365<div class="source">
7366<pre>coll_count( [1, 2, null, missing] );
7367</pre></div></div></li>
7368
7369<li>
7370<p>The expected result is:</p>
7371
7372<div class="source">
7373<div class="source">
7374<pre>4
7375</pre></div></div></li>
7376</ul></div>
7377<div class="section">
7378<h3><a name="coll_avg"></a>coll_avg</h3>
7379
7380<ul>
7381
7382<li>
7383<p>Syntax:</p>
7384
7385<div class="source">
7386<div class="source">
7387<pre>coll_avg(num_collection)
7388</pre></div></div></li>
7389
7390<li>
7391<p>Gets the average value of the numeric items in the given collection.</p></li>
7392
7393<li>Arguments:
7394
7395<ul>
7396
7397<li><tt>num_collection</tt> could be:
7398
7399<ul>
7400
7401<li>an <tt>array</tt> or <tt>multiset</tt> containing numeric values, <tt>null</tt>s or <tt>missing</tt>s,</li>
7402
7403<li>or, a <tt>null</tt> value,</li>
7404
7405<li>or, a <tt>missing</tt> value.</li>
7406 </ul></li>
7407 </ul></li>
7408
7409<li>Return Value:
7410
7411<ul>
7412
7413<li>a <tt>double</tt> value representing the average of the numbers in the given collection,</li>
7414
7415<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
7416
7417<li><tt>null</tt> is returned if there is a <tt>null</tt> or <tt>missing</tt> in the input collection,</li>
7418
7419<li>any other non-numeric value in the input collection will cause a type error.</li>
7420 </ul></li>
7421
7422<li>
7423<p>Example:</p>
7424
7425<div class="source">
7426<div class="source">
7427<pre>coll_avg( [100, 200, 300] );
7428</pre></div></div></li>
7429
7430<li>
7431<p>The expected result is:</p>
7432
7433<div class="source">
7434<div class="source">
7435<pre>[ 200.0 ]
7436</pre></div></div></li>
7437</ul></div>
7438<div class="section">
7439<h3><a name="coll_sum"></a>coll_sum</h3>
7440
7441<ul>
7442
7443<li>
7444<p>Syntax:</p>
7445
7446<div class="source">
7447<div class="source">
7448<pre>coll_sum(num_collection)
7449</pre></div></div></li>
7450
7451<li>
7452<p>Gets the sum of the items in the given collection.</p></li>
7453
7454<li>Arguments:
7455
7456<ul>
7457
7458<li><tt>num_collection</tt> could be:
7459
7460<ul>
7461
7462<li>an <tt>array</tt> or <tt>multiset</tt> containing numeric values, <tt>null</tt>s or <tt>missing</tt>s,</li>
7463
7464<li>or, a <tt>null</tt> value,</li>
7465
7466<li>or, a <tt>missing</tt> value.</li>
7467 </ul></li>
7468 </ul></li>
7469
7470<li>Return Value:
7471
7472<ul>
7473
7474<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>
7475
7476<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
7477
7478<li><tt>null</tt> is returned if there is a <tt>null</tt> or <tt>missing</tt> in the input collection,</li>
7479
7480<li>any other non-numeric value in the input collection will cause a type error.</li>
7481 </ul></li>
7482
7483<li>
7484<p>Example:</p>
7485
7486<div class="source">
7487<div class="source">
7488<pre>coll_sum( [100, 200, 300] );
7489</pre></div></div></li>
7490
7491<li>
7492<p>The expected result is:</p>
7493
7494<div class="source">
7495<div class="source">
7496<pre>600
7497</pre></div></div></li>
7498</ul></div>
7499<div class="section">
7500<h3><a name="array_min"></a>array_min</h3>
7501
7502<ul>
7503
7504<li>
7505<p>Syntax:</p>
7506
7507<div class="source">
7508<div class="source">
7509<pre>coll_min(num_collection)
7510</pre></div></div></li>
7511
7512<li>
7513<p>Gets the min value of comparable items in the given collection.</p></li>
7514
7515<li>Arguments:
7516
7517<ul>
7518
7519<li><tt>num_collection</tt> could be:
7520
7521<ul>
7522
7523<li>an <tt>array</tt> or <tt>multiset</tt>,</li>
7524
7525<li>or, a <tt>null</tt> value,</li>
7526
7527<li>or, a <tt>missing</tt> value.</li>
7528 </ul></li>
7529 </ul></li>
7530
7531<li>Return Value:
7532
7533<ul>
7534
7535<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>
7536
7537<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
7538
7539<li><tt>null</tt> is returned if there is a <tt>null</tt> or <tt>missing</tt> in the input collection,</li>
7540
7541<li>multiple incomparable items in the input array or multiset will cause a type error,</li>
7542
7543<li>any other non-array and non-multiset input value will cause a type error.</li>
7544 </ul></li>
7545
7546<li>
7547<p>Example:</p>
7548
7549<div class="source">
7550<div class="source">
7551<pre>coll_min( [10.2, 100, 5] );
7552</pre></div></div></li>
7553
7554<li>
7555<p>The expected result is:</p>
7556
7557<div class="source">
7558<div class="source">
7559<pre>5.0
7560</pre></div></div></li>
7561</ul></div>
7562<div class="section">
7563<h3><a name="array_max"></a>array_max</h3>
7564
7565<ul>
7566
7567<li>
7568<p>Syntax:</p>
7569
7570<div class="source">
7571<div class="source">
7572<pre>coll_max(num_collection)
7573</pre></div></div></li>
7574
7575<li>
7576<p>Gets the max value of numeric items in the given collection.</p></li>
7577
7578<li>Arguments:
7579
7580<ul>
7581
7582<li><tt>num_collection</tt> could be:
7583
7584<ul>
7585
7586<li>an <tt>array</tt> or <tt>multiset</tt>,</li>
7587
7588<li>or, a <tt>null</tt> value,</li>
7589
7590<li>or, a <tt>missing</tt> value.</li>
7591 </ul></li>
7592 </ul></li>
7593
7594<li>Return Value:
7595
7596<ul>
7597
7598<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>
7599
7600<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
7601
7602<li><tt>null</tt> is returned if there is a <tt>null</tt> or <tt>missing</tt> in the input collection,</li>
7603
7604<li>multiple incomparable items in the input array or multiset will cause a type error,</li>
7605
7606<li>any other non-array and non-multiset input value will cause a type error.</li>
7607 </ul></li>
7608
7609<li>
7610<p>Example:</p>
7611
7612<div class="source">
7613<div class="source">
7614<pre>coll_max( [10.2, 100, 5] );
7615</pre></div></div></li>
7616
7617<li>
7618<p>The expected result is:</p>
7619
7620<div class="source">
7621<div class="source">
7622<pre>100.0
7623</pre></div></div></li>
7624</ul>
7625<!-- ! Licensed to the Apache Software Foundation (ASF) under one
7626 ! or more contributor license agreements. See the NOTICE file
7627 ! distributed with this work for additional information
7628 ! regarding copyright ownership. The ASF licenses this file
7629 ! to you under the Apache License, Version 2.0 (the
7630 ! "License"); you may not use this file except in compliance
7631 ! with the License. You may obtain a copy of the License at
7632 !
7633 ! http://www.apache.org/licenses/LICENSE-2.0
7634 !
7635 ! Unless required by applicable law or agreed to in writing,
7636 ! software distributed under the License is distributed on an
7637 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
7638 ! KIND, either express or implied. See the License for the
7639 ! specific language governing permissions and limitations
7640 ! under the License.
7641 ! --></div></div>
7642<div class="section">
7643<h2><a name="Comparison_Functions"></a><a name="ComparisonFunctions" id="ComparisonFunctions">Comparison Functions</a></h2>
7644<div class="section">
7645<h3><a name="greatest"></a>greatest</h3>
7646
7647<ul>
7648
7649<li>
7650<p>Syntax:</p>
7651
7652<div class="source">
7653<div class="source">
7654<pre>greatest(numeric_value1, numeric_value2, ...)
7655</pre></div></div></li>
7656
7657<li>
7658<p>Computes the greatest value among arguments.</p></li>
7659
7660<li>Arguments:
7661
7662<ul>
7663
7664<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>
7665
7666<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>
7667
7668<li>&#x2026;.</li>
7669 </ul></li>
7670
7671<li>Return Value:
7672
7673<ul>
7674
7675<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>
7676
7677<li><tt>null</tt> if any argument is a <tt>missing</tt> value or <tt>null</tt> value,</li>
7678
7679<li>any other non-numeric input value will cause a type error.</li>
7680 </ul></li>
7681
7682<li>
7683<p>Example:</p>
7684
7685<div class="source">
7686<div class="source">
7687<pre>{ &quot;v1&quot;: greatest(1, 2, 3), &quot;v2&quot;: greatest(float(&quot;0.5&quot;), double(&quot;-0.5&quot;), 5000) };
7688</pre></div></div></li>
7689</ul>
7690
7691<ul>
7692
7693<li>
7694<p>The expected result is:</p>
7695
7696<div class="source">
7697<div class="source">
7698<pre>{ &quot;v1&quot;: 3, &quot;v2&quot;: 5000.0 }
7699</pre></div></div></li>
7700</ul></div>
7701<div class="section">
7702<h3><a name="least"></a>least</h3>
7703
7704<ul>
7705
7706<li>
7707<p>Syntax:</p>
7708
7709<div class="source">
7710<div class="source">
7711<pre>least(numeric_value1, numeric_value2, ...)
7712</pre></div></div></li>
7713
7714<li>
7715<p>Computes the least value among arguments.</p></li>
7716
7717<li>Arguments:
7718
7719<ul>
7720
7721<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>
7722
7723<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>
7724
7725<li>&#x2026;.</li>
7726 </ul></li>
7727
7728<li>Return Value:
7729
7730<ul>
7731
7732<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>
7733
7734<li><tt>null</tt> if any argument is a <tt>missing</tt> value or <tt>null</tt> value,</li>
7735
7736<li>any other non-numeric input value will cause a type error.</li>
7737 </ul></li>
7738
7739<li>
7740<p>Example:</p>
7741
7742<div class="source">
7743<div class="source">
7744<pre>{ &quot;v1&quot;: least(1, 2, 3), &quot;v2&quot;: least(float(&quot;0.5&quot;), double(&quot;-0.5&quot;), 5000) };
7745</pre></div></div></li>
7746</ul>
7747
7748<ul>
7749
7750<li>
7751<p>The expected result is:</p>
7752
7753<div class="source">
7754<div class="source">
7755<pre>{ &quot;v1&quot;: 1, &quot;v2&quot;: -0.5 }
7756</pre></div></div></li>
7757</ul>
7758<!-- ! Licensed to the Apache Software Foundation (ASF) under one
7759 ! or more contributor license agreements. See the NOTICE file
7760 ! distributed with this work for additional information
7761 ! regarding copyright ownership. The ASF licenses this file
7762 ! to you under the Apache License, Version 2.0 (the
7763 ! "License"); you may not use this file except in compliance
7764 ! with the License. You may obtain a copy of the License at
7765 !
7766 ! http://www.apache.org/licenses/LICENSE-2.0
7767 !
7768 ! Unless required by applicable law or agreed to in writing,
7769 ! software distributed under the License is distributed on an
7770 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
7771 ! KIND, either express or implied. See the License for the
7772 ! specific language governing permissions and limitations
7773 ! under the License.
7774 ! --></div></div>
7775<div class="section">
7776<h2><a name="Type_Functions"></a><a name="TypeFunctions" id="TypeFunctions">Type Functions</a></h2>
7777<div class="section">
7778<h3><a name="is_array_isarray"></a>is_array (isarray)</h3>
7779
7780<ul>
7781
7782<li>
7783<p>Syntax:</p>
7784
7785<div class="source">
7786<div class="source">
7787<pre>is_array(expr)
7788</pre></div></div></li>
7789
7790<li>
7791<p>Checks whether the given expression is evaluated to be an <tt>array</tt> value.</p></li>
7792
7793<li>Arguments:
7794
7795<ul>
7796
7797<li><tt>expr</tt> : an expression (any type is allowed).</li>
7798 </ul></li>
7799
7800<li>Return Value:
7801
7802<ul>
7803
7804<li>a <tt>boolean</tt> on whether the argument is an <tt>array</tt> value or not,</li>
7805
7806<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
7807
7808<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
7809 </ul></li>
7810
7811<li>
7812<p>Example:</p>
7813
7814<div class="source">
7815<div class="source">
7816<pre>{
7817 &quot;a&quot;: is_array(true),
7818 &quot;b&quot;: is_array(false),
7819 &quot;c&quot;: isarray(null),
7820 &quot;d&quot;: isarray(missing),
7821 &quot;e&quot;: isarray(&quot;d&quot;),
7822 &quot;f&quot;: isarray(4.0),
7823 &quot;g&quot;: isarray(5),
7824 &quot;h&quot;: isarray([&quot;1&quot;, 2]),
7825 &quot;i&quot;: isarray({&quot;a&quot;:1})
7826};
7827</pre></div></div></li>
7828</ul>
7829
7830<ul>
7831
7832<li>
7833<p>The expected result is:</p>
7834
7835<div class="source">
7836<div class="source">
7837<pre>{ &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 }
7838</pre></div></div></li>
7839</ul>
7840<p>The function has an alias <tt>isarray</tt>.</p></div>
7841<div class="section">
7842<h3><a name="is_boolean_isboolean_isbool"></a>is_boolean (isboolean, isbool)</h3>
7843
7844<ul>
7845
7846<li>
7847<p>Syntax:</p>
7848
7849<div class="source">
7850<div class="source">
7851<pre>is_boolean(expr)
7852</pre></div></div></li>
7853
7854<li>
7855<p>Checks whether the given expression is evaluated to be a <tt>boolean</tt> value.</p></li>
7856
7857<li>Arguments:
7858
7859<ul>
7860
7861<li><tt>expr</tt> : an expression (any type is allowed).</li>
7862 </ul></li>
7863
7864<li>Return Value:
7865
7866<ul>
7867
7868<li>a <tt>boolean</tt> on whether the argument is a <tt>boolean</tt> value or not,</li>
7869
7870<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
7871
7872<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
7873 </ul></li>
7874
7875<li>
7876<p>Example:</p>
7877
7878<div class="source">
7879<div class="source">
7880<pre>{
7881 &quot;a&quot;: isboolean(true),
7882 &quot;b&quot;: isboolean(false),
7883 &quot;c&quot;: is_boolean(null),
7884 &quot;d&quot;: is_boolean(missing),
7885 &quot;e&quot;: isbool(&quot;d&quot;),
7886 &quot;f&quot;: isbool(4.0),
7887 &quot;g&quot;: isbool(5),
7888 &quot;h&quot;: isbool([&quot;1&quot;, 2]),
7889 &quot;i&quot;: isbool({&quot;a&quot;:1})
7890};
7891</pre></div></div></li>
7892</ul>
7893
7894<ul>
7895
7896<li>
7897<p>The expected result is:</p>
7898
7899<div class="source">
7900<div class="source">
7901<pre>{ &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 }
7902</pre></div></div></li>
7903</ul>
7904<p>The function has two aliases, <tt>isboolean</tt> or <tt>isbool</tt>.</p></div>
7905<div class="section">
7906<h3><a name="is_number_isnumber_isnum"></a>is_number (isnumber, isnum)</h3>
7907
7908<ul>
7909
7910<li>
7911<p>Syntax:</p>
7912
7913<div class="source">
7914<div class="source">
7915<pre>is_number(expr)
7916</pre></div></div></li>
7917
7918<li>
7919<p>Checks whether the given expression is evaluated to be a numeric value.</p></li>
7920
7921<li>Arguments:
7922
7923<ul>
7924
7925<li><tt>expr</tt> : an expression (any type is allowed).</li>
7926 </ul></li>
7927
7928<li>Return Value:
7929
7930<ul>
7931
7932<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>
7933
7934<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
7935
7936<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
7937 </ul></li>
7938
7939<li>
7940<p>Example:</p>
7941
7942<div class="source">
7943<div class="source">
7944<pre>{
7945 &quot;a&quot;: is_number(true),
7946 &quot;b&quot;: is_number(false),
7947 &quot;c&quot;: isnumber(null),
7948 &quot;d&quot;: isnumber(missing),
7949 &quot;e&quot;: isnumber(&quot;d&quot;),
7950 &quot;f&quot;: isnum(4.0),
7951 &quot;g&quot;: isnum(5),
7952 &quot;h&quot;: isnum([&quot;1&quot;, 2]),
7953 &quot;i&quot;: isnum({&quot;a&quot;:1})
7954};
7955</pre></div></div></li>
7956</ul>
7957
7958<ul>
7959
7960<li>
7961<p>The expected result is:</p>
7962
7963<div class="source">
7964<div class="source">
7965<pre>{ &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 }
7966</pre></div></div></li>
7967</ul>
7968<p>The function has two aliases, <tt>isnumber</tt> or <tt>isnum</tt>.</p></div>
7969<div class="section">
7970<h3><a name="is_object_isobject_isobj"></a>is_object (isobject, isobj)</h3>
7971
7972<ul>
7973
7974<li>
7975<p>Syntax:</p>
7976
7977<div class="source">
7978<div class="source">
7979<pre>is_object(expr)
7980</pre></div></div></li>
7981
7982<li>
7983<p>Checks whether the given expression is evaluated to be a <tt>object</tt> value.</p></li>
7984
7985<li>Arguments:
7986
7987<ul>
7988
7989<li><tt>expr</tt> : an expression (any type is allowed).</li>
7990 </ul></li>
7991
7992<li>Return Value:
7993
7994<ul>
7995
7996<li>a <tt>boolean</tt> on whether the argument is a <tt>object</tt> value or not,</li>
7997
7998<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
7999
8000<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
8001 </ul></li>
8002
8003<li>
8004<p>Example:</p>
8005
8006<div class="source">
8007<div class="source">
8008<pre>{
8009 &quot;a&quot;: is_object(true),
8010 &quot;b&quot;: is_object(false),
8011 &quot;c&quot;: isobject(null),
8012 &quot;d&quot;: isobject(missing),
8013 &quot;e&quot;: isobj(&quot;d&quot;),
8014 &quot;f&quot;: isobj(4.0),
8015 &quot;g&quot;: isobj(5),
8016 &quot;h&quot;: isobj([&quot;1&quot;, 2]),
8017 &quot;i&quot;: isobj({&quot;a&quot;:1})
8018};
8019</pre></div></div></li>
8020</ul>
8021
8022<ul>
8023
8024<li>
8025<p>The expected result is:</p>
8026<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></li>
8027</ul>
8028<p>The function has two aliases, <tt>isobject</tt> or <tt>isobj</tt>.</p></div>
8029<div class="section">
8030<h3><a name="is_string_isstring_isstr"></a>is_string (isstring, isstr)</h3>
8031
8032<ul>
8033
8034<li>
8035<p>Syntax:</p>
8036
8037<div class="source">
8038<div class="source">
8039<pre>is_string(expr)
8040</pre></div></div></li>
8041
8042<li>
8043<p>Checks whether the given expression is evaluated to be a <tt>string</tt> value.</p></li>
8044
8045<li>Arguments:
8046
8047<ul>
8048
8049<li><tt>expr</tt> : an expression (any type is allowed).</li>
8050 </ul></li>
8051
8052<li>Return Value:
8053
8054<ul>
8055
8056<li>a <tt>boolean</tt> on whether the argument is a <tt>string</tt> value or not,</li>
8057
8058<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
8059
8060<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
8061 </ul></li>
8062
8063<li>
8064<p>Example:</p>
8065
8066<div class="source">
8067<div class="source">
8068<pre>{
8069 &quot;a&quot;: is_string(true),
8070 &quot;b&quot;: isstring(false),
8071 &quot;c&quot;: isstring(null),
8072 &quot;d&quot;: isstr(missing),
8073 &quot;e&quot;: isstr(&quot;d&quot;),
8074 &quot;f&quot;: isstr(4.0),
8075 &quot;g&quot;: isstr(5),
8076 &quot;h&quot;: isstr([&quot;1&quot;, 2]),
8077 &quot;i&quot;: isstr({&quot;a&quot;:1})
8078};
8079</pre></div></div></li>
8080</ul>
8081
8082<ul>
8083
8084<li>
8085<p>The expected result is:</p>
8086
8087<div class="source">
8088<div class="source">
8089<pre>{ &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 }
8090</pre></div></div></li>
8091</ul>
8092<p>The function has two aliases, <tt>isstring</tt> or <tt>isstr</tt>.</p></div>
8093<div class="section">
8094<h3><a name="is_null"></a>is_null</h3>
8095
8096<ul>
8097
8098<li>
8099<p>Syntax:</p>
8100
8101<div class="source">
8102<div class="source">
8103<pre>is_null(expr)
8104</pre></div></div></li>
8105
8106<li>
8107<p>Checks whether the given expression is evaluated to be a <tt>null</tt> value.</p></li>
8108
8109<li>Arguments:
8110
8111<ul>
8112
8113<li><tt>expr</tt> : an expression (any type is allowed).</li>
8114 </ul></li>
8115
8116<li>Return Value:
8117
8118<ul>
8119
8120<li>a <tt>boolean</tt> on whether the variable is a <tt>null</tt> or not,</li>
8121
8122<li>a <tt>missing</tt> if the input is <tt>missing</tt>.</li>
8123 </ul></li>
8124
8125<li>
8126<p>Example:</p>
8127
8128<div class="source">
8129<div class="source">
8130<pre>{ &quot;v1&quot;: is_null(null), &quot;v2&quot;: is_null(1), &quot;v3&quot;: is_null(missing) };
8131</pre></div></div></li>
8132</ul>
8133
8134<ul>
8135
8136<li>
8137<p>The expected result is:</p>
8138
8139<div class="source">
8140<div class="source">
8141<pre>{ &quot;v1&quot;: true, &quot;v2&quot;: false }
8142</pre></div></div></li>
8143</ul>
8144<p>The function has an alias <tt>isnull</tt>.</p></div>
8145<div class="section">
8146<h3><a name="is_missing"></a>is_missing</h3>
8147
8148<ul>
8149
8150<li>
8151<p>Syntax:</p>
8152
8153<div class="source">
8154<div class="source">
8155<pre>is_missing(expr)
8156</pre></div></div></li>
8157
8158<li>
8159<p>Checks whether the given expression is evaluated to be a <tt>missing</tt> value.</p></li>
8160
8161<li>Arguments:
8162
8163<ul>
8164
8165<li><tt>expr</tt> : an expression (any type is allowed).</li>
8166 </ul></li>
8167
8168<li>Return Value:
8169
8170<ul>
8171
8172<li>a <tt>boolean</tt> on whether the variable is a <tt>missing</tt> or not.</li>
8173 </ul></li>
8174
8175<li>
8176<p>Example:</p>
8177
8178<div class="source">
8179<div class="source">
8180<pre>{ &quot;v1&quot;: is_missing(null), &quot;v2&quot;: is_missing(1), &quot;v3&quot;: is_missing(missing) };
8181</pre></div></div></li>
8182</ul>
8183
8184<ul>
8185
8186<li>
8187<p>The expected result is:</p>
8188
8189<div class="source">
8190<div class="source">
8191<pre>{ &quot;v1&quot;: false, &quot;v2&quot;: false, &quot;v3&quot;: true }
8192</pre></div></div></li>
8193</ul>
8194<p>The function has an alias <tt>ismissing</tt>.</p></div>
8195<div class="section">
8196<h3><a name="is_unknown"></a>is_unknown</h3>
8197
8198<ul>
8199
8200<li>
8201<p>Syntax:</p>
8202
8203<div class="source">
8204<div class="source">
8205<pre>is_unknown(expr)
8206</pre></div></div></li>
8207
8208<li>
8209<p>Checks whether the given variable is a <tt>null</tt> value or a <tt>missing</tt> value.</p></li>
8210
8211<li>Arguments:
8212
8213<ul>
8214
8215<li><tt>expr</tt> : an expression (any type is allowed).</li>
8216 </ul></li>
8217
8218<li>Return Value:
8219
8220<ul>
8221
8222<li>a <tt>boolean</tt> on whether the variable is a <tt>null</tt>/`<tt>missing</tt> value (<tt>true</tt>) or not (<tt>false</tt>).</li>
8223 </ul></li>
8224
8225<li>
8226<p>Example:</p>
8227
8228<div class="source">
8229<div class="source">
8230<pre>{ &quot;v1&quot;: is_unknown(null), &quot;v2&quot;: is_unknown(1), &quot;v3&quot;: is_unknown(missing) };
8231</pre></div></div></li>
8232</ul>
8233
8234<ul>
8235
8236<li>
8237<p>The expected result is:</p>
8238
8239<div class="source">
8240<div class="source">
8241<pre>{ &quot;v1&quot;: true, &quot;v2&quot;: false, &quot;v3&quot;: true }
8242</pre></div></div></li>
8243</ul>
8244<p>The function has an alias <tt>isunknown</tt>.</p></div>
8245<div class="section">
8246<h3><a name="to_boolean"></a>to_boolean</h3>
8247
8248<ul>
8249
8250<li>
8251<p>Syntax:</p>
8252
8253<div class="source">
8254<div class="source">
8255<pre>to_boolean(expr)
8256</pre></div></div></li>
8257
8258<li>
8259<p>Converts input value to a <tt>boolean</tt> value</p></li>
8260
8261<li>Arguments:
8262
8263<ul>
8264
8265<li><tt>expr</tt> : an expression</li>
8266 </ul></li>
8267
8268<li>Return Value:
8269
8270<ul>
8271
8272<li>if the argument is <tt>missing</tt> then <tt>missing</tt> is returned</li>
8273
8274<li>if the argument is <tt>null</tt> then <tt>null</tt> is returned</li>
8275
8276<li>if the argument is of <tt>boolean</tt> type then it is returned as is</li>
8277
8278<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>
8279
8280<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>
8281
8282<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>
8283
8284<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>
8285
8286<li>type error is raised for all other input types</li>
8287 </ul></li>
8288
8289<li>
8290<p>Example:</p>
8291
8292<div class="source">
8293<div class="source">
8294<pre>{
8295 &quot;v1&quot;: to_boolean(0),
8296 &quot;v2&quot;: to_boolean(1),
8297 &quot;v3&quot;: to_boolean(&quot;&quot;),
8298 &quot;v4&quot;: to_boolean(&quot;asterix&quot;)
8299};
8300</pre></div></div></li>
8301
8302<li>
8303<p>The expected result is:</p>
8304
8305<div class="source">
8306<div class="source">
8307<pre>{ &quot;v1&quot;: false, &quot;v2&quot;: true, &quot;v3&quot;: false, &quot;v4&quot;: true }
8308</pre></div></div></li>
8309</ul>
8310<p>The function has an alias <tt>toboolean</tt>.</p></div>
8311<div class="section">
8312<h3><a name="to_bigint"></a>to_bigint</h3>
8313
8314<ul>
8315
8316<li>
8317<p>Syntax:</p>
8318
8319<div class="source">
8320<div class="source">
8321<pre>to_bigint(expr)
8322</pre></div></div></li>
8323
8324<li>
8325<p>Converts input value to an integer value</p></li>
8326
8327<li>Arguments:
8328
8329<ul>
8330
8331<li><tt>expr</tt> : an expression</li>
8332 </ul></li>
8333
8334<li>Return Value:
8335
8336<ul>
8337
8338<li>if the argument is <tt>missing</tt> then <tt>missing</tt> is returned</li>
8339
8340<li>if the argument is <tt>null</tt> then <tt>null</tt> is returned</li>
8341
8342<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>
8343
8344<li>if the argument is of numeric integer type then it is returned as the same value of <tt>bigint</tt> type</li>
8345
8346<li>if the argument is of numeric <tt>float</tt>/<tt>double</tt> type then it is converted to <tt>bigint</tt> type</li>
8347
8348<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>
8349
8350<li>if the argument is of <tt>array</tt>/<tt>multiset</tt>/<tt>object</tt> type then <tt>null</tt> is returned</li>
8351
8352<li>type error is raised for all other input types</li>
8353 </ul></li>
8354
8355<li>
8356<p>Example:</p>
8357
8358<div class="source">
8359<div class="source">
8360<pre>{
8361 &quot;v1&quot;: to_bigint(false),
8362 &quot;v2&quot;: to_bigint(true),
8363 &quot;v3&quot;: to_bigint(10),
8364 &quot;v4&quot;: to_bigint(float(&quot;1e100&quot;)),
8365 &quot;v5&quot;: to_bigint(double(&quot;1e1000&quot;)),
8366 &quot;v6&quot;: to_bigint(&quot;20&quot;)
8367};
8368</pre></div></div></li>
8369
8370<li>
8371<p>The expected result is:</p>
8372
8373<div class="source">
8374<div class="source">
8375<pre>{ &quot;v1&quot;: 0, &quot;v2&quot;: 1, &quot;v3&quot;: 10, &quot;v4&quot;: 9223372036854775807, &quot;v5&quot;: 9223372036854775807, &quot;v6&quot;: 20 }
8376</pre></div></div></li>
8377</ul>
8378<p>The function has an alias <tt>tobigint</tt>.</p></div>
8379<div class="section">
8380<h3><a name="to_double"></a>to_double</h3>
8381
8382<ul>
8383
8384<li>
8385<p>Syntax:</p>
8386
8387<div class="source">
8388<div class="source">
8389<pre>to_double(expr)
8390</pre></div></div></li>
8391
8392<li>
8393<p>Converts input value to a <tt>double</tt> value</p></li>
8394
8395<li>Arguments:
8396
8397<ul>
8398
8399<li><tt>expr</tt> : an expression</li>
8400 </ul></li>
8401
8402<li>Return Value:
8403
8404<ul>
8405
8406<li>if the argument is <tt>missing</tt> then <tt>missing</tt> is returned</li>
8407
8408<li>if the argument is <tt>null</tt> then <tt>null</tt> is returned</li>
8409
8410<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>
8411
8412<li>if the argument is of numeric type then it is returned as the value of <tt>double</tt> type</li>
8413
8414<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>
8415
8416<li>if the argument is of <tt>array</tt>/<tt>multiset</tt>/<tt>object</tt> type then <tt>null</tt> is returned</li>
8417
8418<li>type error is raised for all other input types</li>
8419 </ul></li>
8420
8421<li>
8422<p>Example:</p>
8423
8424<div class="source">
8425<div class="source">
8426<pre>{
8427 &quot;v1&quot;: to_double(false),
8428 &quot;v2&quot;: to_double(true),
8429 &quot;v3&quot;: to_double(10),
8430 &quot;v4&quot;: to_double(11.5),
8431 &quot;v5&quot;: to_double(&quot;12.5&quot;)
8432};
8433</pre></div></div></li>
8434
8435<li>
8436<p>The expected result is:</p>
8437
8438<div class="source">
8439<div class="source">
8440<pre>{ &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 }
8441</pre></div></div></li>
8442</ul>
8443<p>The function has an alias <tt>todouble</tt>.</p></div>
8444<div class="section">
8445<h3><a name="to_string"></a>to_string</h3>
8446
8447<ul>
8448
8449<li>
8450<p>Syntax:</p>
8451
8452<div class="source">
8453<div class="source">
8454<pre>to_string(expr)
8455</pre></div></div></li>
8456
8457<li>
8458<p>Converts input value to a string value</p></li>
8459
8460<li>Arguments:
8461
8462<ul>
8463
8464<li><tt>expr</tt> : an expression</li>
8465 </ul></li>
8466
8467<li>Return Value:
8468
8469<ul>
8470
8471<li>if the argument is <tt>missing</tt> then <tt>missing</tt> is returned</li>
8472
8473<li>if the argument is <tt>null</tt> then <tt>null</tt> is returned</li>
8474
8475<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>
8476
8477<li>if the argument is of numeric type then its string representation is returned</li>
8478
8479<li>if the argument is of <tt>string</tt> type then it is returned as is</li>
8480
8481<li>if the argument is of <tt>array</tt>/<tt>multiset</tt>/<tt>object</tt> type then <tt>null</tt> is returned</li>
8482
8483<li>type error is raised for all other input types</li>
8484 </ul></li>
8485
8486<li>
8487<p>Example:</p>
8488
8489<div class="source">
8490<div class="source">
8491<pre>{
8492 &quot;v1&quot;: to_string(false),
8493 &quot;v2&quot;: to_string(true),
8494 &quot;v3&quot;: to_string(10),
8495 &quot;v4&quot;: to_string(11.5),
8496 &quot;v5&quot;: to_string(&quot;asterix&quot;)
8497};
8498</pre></div></div></li>
8499
8500<li>
8501<p>The expected result is:</p>
8502
8503<div class="source">
8504<div class="source">
8505<pre>{ &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; }
8506</pre></div></div></li>
8507</ul>
8508<p>The function has an alias <tt>tostring</tt>. <!-- ! Licensed to the Apache Software Foundation (ASF) under one
8509 ! or more contributor license agreements. See the NOTICE file
8510 ! distributed with this work for additional information
8511 ! regarding copyright ownership. The ASF licenses this file
8512 ! to you under the Apache License, Version 2.0 (the
8513 ! "License"); you may not use this file except in compliance
8514 ! with the License. You may obtain a copy of the License at
8515 !
8516 ! http://www.apache.org/licenses/LICENSE-2.0
8517 !
8518 ! Unless required by applicable law or agreed to in writing,
8519 ! software distributed under the License is distributed on an
8520 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
8521 ! KIND, either express or implied. See the License for the
8522 ! specific language governing permissions and limitations
8523 ! under the License.
8524 ! --></p></div></div>
8525<div class="section">
8526<h2><a name="Conditional_Functions"></a><a name="ConditionalFunctions" id="ConditionalFunctions">Conditional Functions</a></h2>
8527<div class="section">
8528<h3><a name="if_null_ifnull"></a>if_null (ifnull)</h3>
8529
8530<ul>
8531
8532<li>
8533<p>Syntax:</p>
8534
8535<div class="source">
8536<div class="source">
8537<pre>if_null(expression1, expression2, ... expressionN)
8538</pre></div></div></li>
8539
8540<li>
8541<p>Finds first argument which value is not <tt>null</tt> and returns that value</p></li>
8542
8543<li>Arguments:
8544
8545<ul>
8546
8547<li><tt>expressionI</tt> : an expression (any type is allowed).</li>
8548 </ul></li>
8549
8550<li>Return Value:
8551
8552<ul>
8553
8554<li>a <tt>null</tt> if all arguments evaluate to <tt>null</tt> or no arguments specified</li>
8555
8556<li>a value of the first non-<tt>null</tt> argument otherwise</li>
8557 </ul></li>
8558
8559<li>
8560<p>Example:</p>
8561
8562<div class="source">
8563<div class="source">
8564<pre>{
8565 &quot;a&quot;: if_null(),
8566 &quot;b&quot;: if_null(null),
8567 &quot;c&quot;: if_null(null, &quot;asterixdb&quot;),
8568 &quot;d&quot;: is_missing(if_null(missing))
8569};
8570</pre></div></div></li>
8571
8572<li>
8573<p>The expected result is:</p>
8574
8575<div class="source">
8576<div class="source">
8577<pre>{ &quot;a&quot;: null, &quot;b&quot;: null, &quot;c&quot;: &quot;asterixdb&quot;, &quot;d&quot;: true }
8578</pre></div></div></li>
8579</ul>
8580<p>The function has an alias <tt>ifnull</tt>.</p></div>
8581<div class="section">
8582<h3><a name="if_missing_ifmissing"></a>if_missing (ifmissing)</h3>
8583
8584<ul>
8585
8586<li>
8587<p>Syntax:</p>
8588
8589<div class="source">
8590<div class="source">
8591<pre>if_missing(expression1, expression2, ... expressionN)
8592</pre></div></div></li>
8593
8594<li>
8595<p>Finds first argument which value is not <tt>missing</tt> and returns that value</p></li>
8596
8597<li>Arguments:
8598
8599<ul>
8600
8601<li><tt>expressionI</tt> : an expression (any type is allowed).</li>
8602 </ul></li>
8603
8604<li>Return Value:
8605
8606<ul>
8607
8608<li>a <tt>null</tt> if all arguments evaluate to <tt>missing</tt> or no arguments specified</li>
8609
8610<li>a value of the first non-<tt>missing</tt> argument otherwise</li>
8611 </ul></li>
8612
8613<li>
8614<p>Example:</p>
8615
8616<div class="source">
8617<div class="source">
8618<pre>{
8619 &quot;a&quot;: if_missing(),
8620 &quot;b&quot;: if_missing(missing),
8621 &quot;c&quot;: if_missing(missing, &quot;asterixdb&quot;),
8622 &quot;d&quot;: if_missing(null, &quot;asterixdb&quot;)
8623};
8624</pre></div></div></li>
8625
8626<li>
8627<p>The expected result is:</p>
8628
8629<div class="source">
8630<div class="source">
8631<pre>{ &quot;a&quot;: null, &quot;b&quot;: null, &quot;c&quot;: &quot;asterixdb&quot;, &quot;d&quot;: null }
8632</pre></div></div></li>
8633</ul>
8634<p>The function has an alias <tt>ifmissing</tt>.</p></div>
8635<div class="section">
8636<h3><a name="if_missing_or_null_ifmissingornull"></a>if_missing_or_null (ifmissingornull)</h3>
8637
8638<ul>
8639
8640<li>
8641<p>Syntax:</p>
8642
8643<div class="source">
8644<div class="source">
8645<pre>if_missing_or_null(expression1, expression2, ... expressionN)
8646</pre></div></div></li>
8647
8648<li>
8649<p>Finds first argument which value is not <tt>null</tt> or <tt>missing</tt> and returns that value</p></li>
8650
8651<li>Arguments:
8652
8653<ul>
8654
8655<li><tt>expressionI</tt> : an expression (any type is allowed).</li>
8656 </ul></li>
8657
8658<li>Return Value:
8659
8660<ul>
8661
8662<li>a <tt>null</tt> if all arguments evaluate to either <tt>null</tt> or <tt>missing</tt>, or no arguments specified</li>
8663
8664<li>a value of the first non-<tt>null</tt>, non-<tt>missing</tt> argument otherwise</li>
8665 </ul></li>
8666
8667<li>
8668<p>Example:</p>
8669
8670<div class="source">
8671<div class="source">
8672<pre>{
8673 &quot;a&quot;: if_missing_or_null(),
8674 &quot;b&quot;: if_missing_or_null(null, missing),
8675 &quot;c&quot;: if_missing_or_null(null, missing, &quot;asterixdb&quot;)
8676};
8677</pre></div></div></li>
8678
8679<li>
8680<p>The expected result is:</p>
8681
8682<div class="source">
8683<div class="source">
8684<pre>{ &quot;a&quot;: null, &quot;b&quot;: null, &quot;c&quot;: &quot;asterixdb&quot; }
8685</pre></div></div></li>
8686</ul>
8687<p>The function has an alias <tt>ifmissingornull</tt>. <!-- ! Licensed to the Apache Software Foundation (ASF) under one
8688 ! or more contributor license agreements. See the NOTICE file
8689 ! distributed with this work for additional information
8690 ! regarding copyright ownership. The ASF licenses this file
8691 ! to you under the Apache License, Version 2.0 (the
8692 ! "License"); you may not use this file except in compliance
8693 ! with the License. You may obtain a copy of the License at
8694 !
8695 ! http://www.apache.org/licenses/LICENSE-2.0
8696 !
8697 ! Unless required by applicable law or agreed to in writing,
8698 ! software distributed under the License is distributed on an
8699 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
8700 ! KIND, either express or implied. See the License for the
8701 ! specific language governing permissions and limitations
8702 ! under the License.
8703 ! --></p></div></div>
8704<div class="section">
8705<h2><a name="Miscellaneous_Functions"></a><a name="MiscFunctions" id="MiscFunctions">Miscellaneous Functions</a></h2>
8706<div class="section">
8707<h3><a name="uuid"></a>uuid</h3>
8708
8709<ul>
8710
8711<li>
8712<p>Syntax:</p>
8713
8714<div class="source">
8715<div class="source">
8716<pre>uuid()
8717</pre></div></div></li>
8718
8719<li>
8720<p>Generates a <tt>uuid</tt>.</p></li>
8721
8722<li>Arguments:
8723
8724<ul>
8725
8726<li>none</li>
8727 </ul></li>
8728
8729<li>Return Value:
8730
8731<ul>
8732
8733<li>a generated, random <tt>uuid</tt>.</li>
8734 </ul></li>
8735</ul></div>
8736<div class="section">
8737<h3><a name="len"></a>len</h3>
8738
8739<ul>
8740
8741<li>
8742<p>Syntax:</p>
8743<p>len(array)</p></li>
8744
8745<li>
8746<p>Returns the length of the array array.</p></li>
8747
8748<li>Arguments:
8749
8750<ul>
8751
8752<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>
8753 </ul></li>
8754
8755<li>Return Value:
8756
8757<ul>
8758
8759<li>an <tt>integer</tt> that represents the length of input array or the size of the input multiset,</li>
8760
8761<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
8762
8763<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value.</li>
8764 </ul></li>
8765
8766<li>
8767<p>Example:</p>
8768
8769<div class="source">
8770<div class="source">
8771<pre>len([&quot;Hello&quot;, &quot;World&quot;])
8772</pre></div></div></li>
8773</ul>
8774
8775<ul>
8776
8777<li>
8778<p>The expected result is:</p>
8779
8780<div class="source">
8781<div class="source">
8782<pre>2
8783</pre></div></div></li>
8784</ul></div>
8785<div class="section">
8786<h3><a name="not"></a>not</h3>
8787
8788<ul>
8789
8790<li>
8791<p>Syntax:</p>
8792
8793<div class="source">
8794<div class="source">
8795<pre>not(expr)
8796</pre></div></div></li>
8797
8798<li>
8799<p>Inverts a <tt>boolean</tt> value</p></li>
8800
8801<li>Arguments:
8802
8803<ul>
8804
8805<li><tt>expr</tt> : an expression</li>
8806 </ul></li>
8807
8808<li>Return Value:
8809
8810<ul>
8811
8812<li>a <tt>boolean</tt>, the inverse of <tt>expr</tt>,</li>
8813
8814<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
8815
8816<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
8817
8818<li>other non-boolean argument value will cause a type error.</li>
8819 </ul></li>
8820
8821<li>
8822<p>Example:</p>
8823
8824<div class="source">
8825<div class="source">
8826<pre>{ &quot;v1&quot;: `not`(true), &quot;v2&quot;: `not`(false), &quot;v3&quot;: `not`(null), &quot;v4&quot;: `not`(missing) };
8827</pre></div></div></li>
8828
8829<li>
8830<p>The expected result is:</p>
8831
8832<div class="source">
8833<div class="source">
8834<pre>{ &quot;v1&quot;: false, &quot;v2&quot;: true, &quot;v3&quot;: null }
8835</pre></div></div></li>
8836</ul></div>
8837<div class="section">
8838<h3><a name="range"></a>range</h3>
8839
8840<ul>
8841
8842<li>
8843<p>Syntax:</p>
8844
8845<div class="source">
8846<div class="source">
8847<pre>range(start_numeric_value, end_numeric_value)
8848</pre></div></div></li>
8849
8850<li>
8851<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></li>
8852
8853<li>Arguments:</li>
8854
8855<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>
8856
8857<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>
8858
8859<li>Return Value:
8860
8861<ul>
8862
8863<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>
8864 </ul></li>
8865
8866<li>
8867<p>Example:</p>
8868
8869<div class="source">
8870<div class="source">
8871<pre>range(0, 3);
8872</pre></div></div></li>
8873
8874<li>
8875<p>The expected result is:</p>
8876
8877<div class="source">
8878<div class="source">
8879<pre>[ 0, 1, 2, 3 ]
8880</pre></div></div></li>
8881</ul></div>
8882<div class="section">
8883<h3><a name="switch_case"></a>switch_case</h3>
8884
8885<ul>
8886
8887<li>
8888<p>Syntax:</p>
8889
8890<div class="source">
8891<div class="source">
8892<pre>switch_case(
8893 condition,
8894 case1, case1_result,
8895 case2, case2_result,
8896 ...,
8897 default, default_result
8898)
8899</pre></div></div></li>
8900
8901<li>
8902<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></li>
8903
8904<li>Arguments:
8905
8906<ul>
8907
8908<li><tt>condition</tt>: a variable (any type is allowed).</li>
8909
8910<li><tt>caseI/default</tt>: a variable (any type is allowed).</li>
8911
8912<li><tt>caseI/default_result</tt>: a variable (any type is allowed).</li>
8913 </ul></li>
8914
8915<li>Return Value:
8916
8917<ul>
8918
8919<li><tt>caseI_result</tt> if <tt>condition</tt> matches <tt>caseI</tt>, otherwise <tt>default_result</tt>.</li>
8920 </ul></li>
8921
8922<li>
8923<p>Example 1:</p>
8924
8925<div class="source">
8926<div class="source">
8927<pre>switch_case(
8928 &quot;a&quot;,
8929 &quot;a&quot;, 0,
8930 &quot;x&quot;, 1,
8931 &quot;y&quot;, 2,
8932 &quot;z&quot;, 3
8933);
8934</pre></div></div></li>
8935</ul>
8936
8937<ul>
8938
8939<li>
8940<p>The expected result is:</p>
8941
8942<div class="source">
8943<div class="source">
8944<pre>0
8945</pre></div></div></li>
8946
8947<li>
8948<p>Example 2:</p>
8949
8950<div class="source">
8951<div class="source">
8952<pre>switch_case(
8953 &quot;a&quot;,
8954 &quot;x&quot;, 1,
8955 &quot;y&quot;, 2,
8956 &quot;z&quot;, 3
8957);
8958</pre></div></div></li>
8959
8960<li>
8961<p>The expected result is:</p>
8962
8963<div class="source">
8964<div class="source">
8965<pre>3
8966</pre></div></div></li>
8967</ul></div>
8968<div class="section">
8969<h3><a name="deep_equal"></a>deep_equal</h3>
8970
8971<ul>
8972
8973<li>
8974<p>Syntax:</p>
8975
8976<div class="source">
8977<div class="source">
8978<pre>deep_equal(expr1, expr2)
8979</pre></div></div></li>
8980</ul>
8981
8982<ul>
8983
8984<li>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.</li>
8985
8986<li>Arguments:
8987
8988<ul>
8989
8990<li><tt>expr1</tt> : an expression,</li>
8991
8992<li><tt>expr2</tt> : an expression.</li>
8993 </ul></li>
8994
8995<li>Return Value:
8996
8997<ul>
8998
8999<li><tt>true</tt> or <tt>false</tt> depending on the data equality,</li>
9000
9001<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
9002
9003<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value.</li>
9004 </ul></li>
9005</ul>
9006
9007<ul>
9008
9009<li>
9010<p>Example:</p>
9011
9012<div class="source">
9013<div class="source">
9014<pre>deep_equal(
9015 {
9016 &quot;id&quot;:1,
9017 &quot;project&quot;:&quot;AsterixDB&quot;,
9018 &quot;address&quot;:{&quot;city&quot;:&quot;Irvine&quot;, &quot;state&quot;:&quot;CA&quot;},
9019 &quot;related&quot;:[&quot;Hivestrix&quot;, &quot;Preglix&quot;, &quot;Apache VXQuery&quot;]
9020 },
9021 {
9022 &quot;id&quot;:1,
9023 &quot;project&quot;:&quot;AsterixDB&quot;,
9024 &quot;address&quot;:{&quot;city&quot;:&quot;San Diego&quot;, &quot;state&quot;:&quot;CA&quot;},
9025 &quot;related&quot;:[&quot;Hivestrix&quot;, &quot;Preglix&quot;, &quot;Apache VXQuery&quot;]
9026 }
9027);
9028</pre></div></div></li>
9029
9030<li>
9031<p>The expected result is:</p>
9032
9033<div class="source">
9034<div class="source">
9035<pre>false
9036</pre></div></div></li>
9037</ul></div></div>
9038 </div>
9039 </div>
9040 </div>
9041
9042 <hr/>
9043
9044 <footer>
9045 <div class="container-fluid">
9046 <div class="row span12">Copyright &copy; 2017
9047 <a href="https://www.apache.org/">The Apache Software Foundation</a>.
9048 All Rights Reserved.
9049
9050 </div>
9051
9052 <?xml version="1.0" encoding="UTF-8"?>
9053<div class="row-fluid">Apache AsterixDB, AsterixDB, Apache, the Apache
9054 feather logo, and the Apache AsterixDB project logo are either
9055 registered trademarks or trademarks of The Apache Software
9056 Foundation in the United States and other countries.
9057 All other marks mentioned may be trademarks or registered
9058 trademarks of their respective owners.</div>
9059
9060
9061 </div>
9062 </footer>
9063 </body>
9064</html>