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