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