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