Gitiles
Code Review Sign In
asterix-gerrit.ics.uci.edu / incubator-asterixdb-site / 5f34114603bb17e7c3493d060d88bad69e418cda / . / docs / 0.9.1 / sqlpp / builtins.html
blob: 655f514ee55d0d2faeb92cda18b0a95e4daf1338 [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 class="active">
136
137 <a href="#"><i class="none"></i>Builtin Functions</a>
138 </li>
139 <li class="nav-header">Queries - AQL</li>
140
141 <li>
142
143 <a href="../aql/manual.html" title="The Asterix Query Language (AQL)">
144 <i class="none"></i>
145 The Asterix Query Language (AQL)</a>
146 </li>
147
148 <li>
149
150 <a href="../aql/builtins.html" title="Builtin Functions">
151 <i class="none"></i>
152 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>A high-level description of SQL++ aggregate functions can be found at <a href="manual.html#Aggregation_functions">here</a>. As SQL++ supports all legitimate SQL GROUP BY and Aggregation queries, <a href="manual.html#SQL-92_aggregation_functions">here</a> is a description of how standard SQL aggregation functions are supported.</p>
6970<p>This section contains detailed descriptions of each SQL++ aggregate function (i.e., array function).</p>
6971<div class="section">
6972<h3><a name="array_count"></a>array_count</h3>
6973
6974<ul>
6975
6976<li>
6977<p>Syntax:</p>
6978
6979<div class="source">
6980<div class="source">
6981<pre>array_count(collection)
6982</pre></div></div></li>
6983
6984<li>
6985<p>Gets the number of non-null and non-missing items in the given collection.</p></li>
6986
6987<li>Arguments:
6988
6989<ul>
6990
6991<li><tt>collection</tt> could be:
6992
6993<ul>
6994
6995<li>an <tt>array</tt> or <tt>multiset</tt> to be counted,</li>
6996
6997<li>or, a <tt>null</tt> value,</li>
6998
6999<li>or, a <tt>missing</tt> value.</li>
7000 </ul></li>
7001 </ul></li>
7002
7003<li>Return Value:
7004
7005<ul>
7006
7007<li>a <tt>bigint</tt> value representing the number of non-null and non-missing items in the given collection,</li>
7008
7009<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
7010
7011<li>any other non-array and non-multiset input value will cause an error.</li>
7012 </ul></li>
7013
7014<li>
7015<p>Example:</p>
7016
7017<div class="source">
7018<div class="source">
7019<pre>array_count( ['hello', 'world', 1, 2, 3, null, missing] );
7020</pre></div></div></li>
7021</ul>
7022
7023<ul>
7024
7025<li>
7026<p>The expected result is:</p>
7027
7028<div class="source">
7029<div class="source">
7030<pre>5
7031</pre></div></div></li>
7032</ul></div>
7033<div class="section">
7034<h3><a name="array_avg"></a>array_avg</h3>
7035
7036<ul>
7037
7038<li>
7039<p>Syntax:</p>
7040
7041<div class="source">
7042<div class="source">
7043<pre>array_avg(num_collection)
7044</pre></div></div></li>
7045
7046<li>
7047<p>Gets the average value of the non-null and non-missing numeric items in the given collection.</p></li>
7048
7049<li>Arguments:
7050
7051<ul>
7052
7053<li><tt>num_collection</tt> could be:
7054
7055<ul>
7056
7057<li>an <tt>array</tt> or <tt>multiset</tt> containing numeric values, <tt>null</tt>s or <tt>missing</tt>s,</li>
7058
7059<li>or, a <tt>null</tt> value,</li>
7060
7061<li>or, a <tt>missing</tt> value.</li>
7062 </ul></li>
7063 </ul></li>
7064
7065<li>Return Value:
7066
7067<ul>
7068
7069<li>a <tt>double</tt> value representing the average of the non-null and non-missing numbers in the given collection,</li>
7070
7071<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
7072
7073<li><tt>null</tt> is returned if the given collection does not contain any non-null and non-missing items,</li>
7074
7075<li>any other non-array and non-multiset input value will cause a type error,</li>
7076
7077<li>any other non-numeric value in the input collection will cause a type error.</li>
7078 </ul></li>
7079
7080<li>
7081<p>Example:</p>
7082
7083<div class="source">
7084<div class="source">
7085<pre>array_avg( [1.2, 2.3, 3.4, 0, null] );
7086</pre></div></div></li>
7087
7088<li>
7089<p>The expected result is:</p>
7090
7091<div class="source">
7092<div class="source">
7093<pre>1.725
7094</pre></div></div></li>
7095</ul></div>
7096<div class="section">
7097<h3><a name="array_sum"></a>array_sum</h3>
7098
7099<ul>
7100
7101<li>
7102<p>Syntax:</p>
7103
7104<div class="source">
7105<div class="source">
7106<pre>array_sum(num_collection)
7107</pre></div></div></li>
7108
7109<li>
7110<p>Gets the sum of non-null and non-missing items in the given collection.</p></li>
7111
7112<li>Arguments:
7113
7114<ul>
7115
7116<li><tt>num_collection</tt> could be:
7117
7118<ul>
7119
7120<li>an <tt>array</tt> or <tt>multiset</tt> containing numeric values, <tt>null</tt>s or <tt>missing</tt>s,</li>
7121
7122<li>or, a <tt>null</tt> value,</li>
7123
7124<li>or, a <tt>missing</tt> value.</li>
7125 </ul></li>
7126 </ul></li>
7127
7128<li>Return Value:
7129
7130<ul>
7131
7132<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>
7133
7134<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
7135
7136<li><tt>null</tt> is returned if the given collection does not contain any non-null and non-missing items,</li>
7137
7138<li>any other non-array and non-multiset input value will cause a type error,</li>
7139
7140<li>any other non-numeric value in the input collection will cause a type error.</li>
7141 </ul></li>
7142
7143<li>
7144<p>Example:</p>
7145
7146<div class="source">
7147<div class="source">
7148<pre>array_sum( [1.2, 2.3, 3.4, 0, null, missing] );
7149</pre></div></div></li>
7150
7151<li>
7152<p>The expected result is:</p>
7153
7154<div class="source">
7155<div class="source">
7156<pre>6.9
7157</pre></div></div></li>
7158</ul></div>
7159<div class="section">
7160<h3><a name="array_sql_min"></a>array_sql_min</h3>
7161
7162<ul>
7163
7164<li>
7165<p>Syntax:</p>
7166
7167<div class="source">
7168<div class="source">
7169<pre>array_min(num_collection)
7170</pre></div></div></li>
7171
7172<li>
7173<p>Gets the min value of non-null and non-missing comparable items in the given collection.</p></li>
7174
7175<li>Arguments:
7176
7177<ul>
7178
7179<li><tt>num_collection</tt> could be:
7180
7181<ul>
7182
7183<li>an <tt>array</tt> or <tt>multiset</tt>,</li>
7184
7185<li>or, a <tt>null</tt> value,</li>
7186
7187<li>or, a <tt>missing</tt> value.</li>
7188 </ul></li>
7189 </ul></li>
7190
7191<li>Return Value:
7192
7193<ul>
7194
7195<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>
7196
7197<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
7198
7199<li><tt>null</tt> is returned if the given collection does not contain any non-null and non-missing items,</li>
7200
7201<li>multiple incomparable items in the input array or multiset will cause a type error,</li>
7202
7203<li>any other non-array and non-multiset input value will cause a type error.</li>
7204 </ul></li>
7205
7206<li>
7207<p>Example:</p>
7208
7209<div class="source">
7210<div class="source">
7211<pre>array_min( [1.2, 2.3, 3.4, 0, null, missing] );
7212</pre></div></div></li>
7213
7214<li>
7215<p>The expected result is:</p>
7216
7217<div class="source">
7218<div class="source">
7219<pre>0.0
7220</pre></div></div></li>
7221</ul></div>
7222<div class="section">
7223<h3><a name="array_max"></a>array_max</h3>
7224
7225<ul>
7226
7227<li>
7228<p>Syntax:</p>
7229
7230<div class="source">
7231<div class="source">
7232<pre>array_max(num_collection)
7233</pre></div></div></li>
7234
7235<li>
7236<p>Gets the max value of the non-null and non-missing comparable items in the given collection.</p></li>
7237
7238<li>Arguments:
7239
7240<ul>
7241
7242<li><tt>num_collection</tt> could be:
7243
7244<ul>
7245
7246<li>an <tt>array</tt> or <tt>multiset</tt>,</li>
7247
7248<li>or, a <tt>null</tt> value,</li>
7249
7250<li>or, a <tt>missing</tt> value.</li>
7251 </ul></li>
7252 </ul></li>
7253
7254<li>Return Value:
7255
7256<ul>
7257
7258<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>
7259
7260<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
7261
7262<li><tt>null</tt> is returned if the given collection does not contain any non-null and non-missing items,</li>
7263
7264<li>multiple incomparable items in the input array or multiset will cause a type error,</li>
7265
7266<li>any other non-array and non-multiset input value will cause a type error.</li>
7267 </ul></li>
7268
7269<li>
7270<p>Example:</p>
7271
7272<div class="source">
7273<div class="source">
7274<pre>array_max( [1.2, 2.3, 3.4, 0, null, missing] );
7275</pre></div></div></li>
7276
7277<li>
7278<p>The expected result is:</p>
7279
7280<div class="source">
7281<div class="source">
7282<pre>3.4
7283</pre></div></div></li>
7284</ul></div>
7285<div class="section">
7286<h3><a name="coll_count"></a>coll_count</h3>
7287
7288<ul>
7289
7290<li>
7291<p>Syntax:</p>
7292
7293<div class="source">
7294<div class="source">
7295<pre>coll_count(collection)
7296</pre></div></div></li>
7297
7298<li>
7299<p>Gets the number of items in the given collection.</p></li>
7300
7301<li>Arguments:
7302
7303<ul>
7304
7305<li><tt>collection</tt> could be:
7306
7307<ul>
7308
7309<li>an <tt>array</tt> or <tt>multiset</tt> containing the items to be counted,</li>
7310
7311<li>or a <tt>null</tt> value,</li>
7312
7313<li>or a <tt>missing</tt> value.</li>
7314 </ul></li>
7315 </ul></li>
7316
7317<li>Return Value:
7318
7319<ul>
7320
7321<li>a <tt>bigint</tt> value representing the number of items in the given collection,</li>
7322
7323<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>.</li>
7324 </ul></li>
7325
7326<li>
7327<p>Example:</p>
7328
7329<div class="source">
7330<div class="source">
7331<pre>coll_count( [1, 2, null, missing] );
7332</pre></div></div></li>
7333
7334<li>
7335<p>The expected result is:</p>
7336
7337<div class="source">
7338<div class="source">
7339<pre>4
7340</pre></div></div></li>
7341</ul></div>
7342<div class="section">
7343<h3><a name="coll_avg"></a>coll_avg</h3>
7344
7345<ul>
7346
7347<li>
7348<p>Syntax:</p>
7349
7350<div class="source">
7351<div class="source">
7352<pre>coll_avg(num_collection)
7353</pre></div></div></li>
7354
7355<li>
7356<p>Gets the average value of the numeric items in the given collection.</p></li>
7357
7358<li>Arguments:
7359
7360<ul>
7361
7362<li><tt>num_collection</tt> could be:
7363
7364<ul>
7365
7366<li>an <tt>array</tt> or <tt>multiset</tt> containing numeric values, <tt>null</tt>s or <tt>missing</tt>s,</li>
7367
7368<li>or, a <tt>null</tt> value,</li>
7369
7370<li>or, a <tt>missing</tt> value.</li>
7371 </ul></li>
7372 </ul></li>
7373
7374<li>Return Value:
7375
7376<ul>
7377
7378<li>a <tt>double</tt> value representing the average of the numbers in the given collection,</li>
7379
7380<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
7381
7382<li><tt>null</tt> is returned if there is a <tt>null</tt> or <tt>missing</tt> in the input collection,</li>
7383
7384<li>any other non-numeric value in the input collection will cause a type error.</li>
7385 </ul></li>
7386
7387<li>
7388<p>Example:</p>
7389
7390<div class="source">
7391<div class="source">
7392<pre>coll_avg( [100, 200, 300] );
7393</pre></div></div></li>
7394
7395<li>
7396<p>The expected result is:</p>
7397
7398<div class="source">
7399<div class="source">
7400<pre>[ 200.0 ]
7401</pre></div></div></li>
7402</ul></div>
7403<div class="section">
7404<h3><a name="coll_sum"></a>coll_sum</h3>
7405
7406<ul>
7407
7408<li>
7409<p>Syntax:</p>
7410
7411<div class="source">
7412<div class="source">
7413<pre>coll_sum(num_collection)
7414</pre></div></div></li>
7415
7416<li>
7417<p>Gets the sum of the items in the given collection.</p></li>
7418
7419<li>Arguments:
7420
7421<ul>
7422
7423<li><tt>num_collection</tt> could be:
7424
7425<ul>
7426
7427<li>an <tt>array</tt> or <tt>multiset</tt> containing numeric values, <tt>null</tt>s or <tt>missing</tt>s,</li>
7428
7429<li>or, a <tt>null</tt> value,</li>
7430
7431<li>or, a <tt>missing</tt> value.</li>
7432 </ul></li>
7433 </ul></li>
7434
7435<li>Return Value:
7436
7437<ul>
7438
7439<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>
7440
7441<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
7442
7443<li><tt>null</tt> is returned if there is a <tt>null</tt> or <tt>missing</tt> in the input collection,</li>
7444
7445<li>any other non-numeric value in the input collection will cause a type error.</li>
7446 </ul></li>
7447
7448<li>
7449<p>Example:</p>
7450
7451<div class="source">
7452<div class="source">
7453<pre>coll_sum( [100, 200, 300] );
7454</pre></div></div></li>
7455
7456<li>
7457<p>The expected result is:</p>
7458
7459<div class="source">
7460<div class="source">
7461<pre>600
7462</pre></div></div></li>
7463</ul></div>
7464<div class="section">
7465<h3><a name="array_min"></a>array_min</h3>
7466
7467<ul>
7468
7469<li>
7470<p>Syntax:</p>
7471
7472<div class="source">
7473<div class="source">
7474<pre>coll_min(num_collection)
7475</pre></div></div></li>
7476
7477<li>
7478<p>Gets the min value of comparable items in the given collection.</p></li>
7479
7480<li>Arguments:
7481
7482<ul>
7483
7484<li><tt>num_collection</tt> could be:
7485
7486<ul>
7487
7488<li>an <tt>array</tt> or <tt>multiset</tt>,</li>
7489
7490<li>or, a <tt>null</tt> value,</li>
7491
7492<li>or, a <tt>missing</tt> value.</li>
7493 </ul></li>
7494 </ul></li>
7495
7496<li>Return Value:
7497
7498<ul>
7499
7500<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>
7501
7502<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
7503
7504<li><tt>null</tt> is returned if there is a <tt>null</tt> or <tt>missing</tt> in the input collection,</li>
7505
7506<li>multiple incomparable items in the input array or multiset will cause a type error,</li>
7507
7508<li>any other non-array and non-multiset input value will cause a type error.</li>
7509 </ul></li>
7510
7511<li>
7512<p>Example:</p>
7513
7514<div class="source">
7515<div class="source">
7516<pre>coll_min( [10.2, 100, 5] );
7517</pre></div></div></li>
7518
7519<li>
7520<p>The expected result is:</p>
7521
7522<div class="source">
7523<div class="source">
7524<pre>5.0
7525</pre></div></div></li>
7526</ul></div>
7527<div class="section">
7528<h3><a name="array_max"></a>array_max</h3>
7529
7530<ul>
7531
7532<li>
7533<p>Syntax:</p>
7534
7535<div class="source">
7536<div class="source">
7537<pre>coll_max(num_collection)
7538</pre></div></div></li>
7539
7540<li>
7541<p>Gets the max value of numeric items in the given collection.</p></li>
7542
7543<li>Arguments:
7544
7545<ul>
7546
7547<li><tt>num_collection</tt> could be:
7548
7549<ul>
7550
7551<li>an <tt>array</tt> or <tt>multiset</tt>,</li>
7552
7553<li>or, a <tt>null</tt> value,</li>
7554
7555<li>or, a <tt>missing</tt> value.</li>
7556 </ul></li>
7557 </ul></li>
7558
7559<li>Return Value:
7560
7561<ul>
7562
7563<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>
7564
7565<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
7566
7567<li><tt>null</tt> is returned if there is a <tt>null</tt> or <tt>missing</tt> in the input collection,</li>
7568
7569<li>multiple incomparable items in the input array or multiset will cause a type error,</li>
7570
7571<li>any other non-array and non-multiset input value will cause a type error.</li>
7572 </ul></li>
7573
7574<li>
7575<p>Example:</p>
7576
7577<div class="source">
7578<div class="source">
7579<pre>coll_max( [10.2, 100, 5] );
7580</pre></div></div></li>
7581
7582<li>
7583<p>The expected result is:</p>
7584
7585<div class="source">
7586<div class="source">
7587<pre>100.0
7588</pre></div></div></li>
7589</ul>
7590<!-- ! Licensed to the Apache Software Foundation (ASF) under one
7591 ! or more contributor license agreements. See the NOTICE file
7592 ! distributed with this work for additional information
7593 ! regarding copyright ownership. The ASF licenses this file
7594 ! to you under the Apache License, Version 2.0 (the
7595 ! "License"); you may not use this file except in compliance
7596 ! with the License. You may obtain a copy of the License at
7597 !
7598 ! http://www.apache.org/licenses/LICENSE-2.0
7599 !
7600 ! Unless required by applicable law or agreed to in writing,
7601 ! software distributed under the License is distributed on an
7602 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
7603 ! KIND, either express or implied. See the License for the
7604 ! specific language governing permissions and limitations
7605 ! under the License.
7606 ! --></div></div>
7607<div class="section">
7608<h2><a name="Comparison_Functions"></a><a name="ComparisonFunctions" id="ComparisonFunctions">Comparison Functions</a></h2>
7609<div class="section">
7610<h3><a name="greatest"></a>greatest</h3>
7611
7612<ul>
7613
7614<li>
7615<p>Syntax:</p>
7616
7617<div class="source">
7618<div class="source">
7619<pre>greatest(numeric_value1, numeric_value2, ...)
7620</pre></div></div></li>
7621
7622<li>
7623<p>Computes the greatest value among arguments.</p></li>
7624
7625<li>Arguments:
7626
7627<ul>
7628
7629<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>
7630
7631<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>
7632
7633<li>&#x2026;.</li>
7634 </ul></li>
7635
7636<li>Return Value:
7637
7638<ul>
7639
7640<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>
7641
7642<li><tt>null</tt> if any argument is a <tt>missing</tt> value or <tt>null</tt> value,</li>
7643
7644<li>any other non-numeric input value will cause a type error.</li>
7645 </ul></li>
7646
7647<li>
7648<p>Example:</p>
7649
7650<div class="source">
7651<div class="source">
7652<pre>{ &quot;v1&quot;: greatest(1, 2, 3), &quot;v2&quot;: greatest(float(&quot;0.5&quot;), double(&quot;-0.5&quot;), 5000) };
7653</pre></div></div></li>
7654</ul>
7655
7656<ul>
7657
7658<li>
7659<p>The expected result is:</p>
7660
7661<div class="source">
7662<div class="source">
7663<pre>{ &quot;v1&quot;: 3, &quot;v2&quot;: 5000.0 }
7664</pre></div></div></li>
7665</ul></div>
7666<div class="section">
7667<h3><a name="least"></a>least</h3>
7668
7669<ul>
7670
7671<li>
7672<p>Syntax:</p>
7673
7674<div class="source">
7675<div class="source">
7676<pre>least(numeric_value1, numeric_value2, ...)
7677</pre></div></div></li>
7678
7679<li>
7680<p>Computes the least value among arguments.</p></li>
7681
7682<li>Arguments:
7683
7684<ul>
7685
7686<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>
7687
7688<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>
7689
7690<li>&#x2026;.</li>
7691 </ul></li>
7692
7693<li>Return Value:
7694
7695<ul>
7696
7697<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>
7698
7699<li><tt>null</tt> if any argument is a <tt>missing</tt> value or <tt>null</tt> value,</li>
7700
7701<li>any other non-numeric input value will cause a type error.</li>
7702 </ul></li>
7703
7704<li>
7705<p>Example:</p>
7706
7707<div class="source">
7708<div class="source">
7709<pre>{ &quot;v1&quot;: least(1, 2, 3), &quot;v2&quot;: least(float(&quot;0.5&quot;), double(&quot;-0.5&quot;), 5000) };
7710</pre></div></div></li>
7711</ul>
7712
7713<ul>
7714
7715<li>
7716<p>The expected result is:</p>
7717
7718<div class="source">
7719<div class="source">
7720<pre>{ &quot;v1&quot;: 1, &quot;v2&quot;: -0.5 }
7721</pre></div></div></li>
7722</ul>
7723<!-- ! Licensed to the Apache Software Foundation (ASF) under one
7724 ! or more contributor license agreements. See the NOTICE file
7725 ! distributed with this work for additional information
7726 ! regarding copyright ownership. The ASF licenses this file
7727 ! to you under the Apache License, Version 2.0 (the
7728 ! "License"); you may not use this file except in compliance
7729 ! with the License. You may obtain a copy of the License at
7730 !
7731 ! http://www.apache.org/licenses/LICENSE-2.0
7732 !
7733 ! Unless required by applicable law or agreed to in writing,
7734 ! software distributed under the License is distributed on an
7735 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
7736 ! KIND, either express or implied. See the License for the
7737 ! specific language governing permissions and limitations
7738 ! under the License.
7739 ! --></div></div>
7740<div class="section">
7741<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>
7742<div class="section">
7743<h3><a name="is_array_isarray"></a>is_array (isarray)</h3>
7744
7745<ul>
7746
7747<li>
7748<p>Syntax:</p>
7749
7750<div class="source">
7751<div class="source">
7752<pre>is_array(expr)
7753</pre></div></div></li>
7754
7755<li>
7756<p>Checks whether the given expression is evaluated to be an <tt>array</tt> value.</p></li>
7757
7758<li>Arguments:
7759
7760<ul>
7761
7762<li><tt>expr</tt> : an expression (any type is allowed).</li>
7763 </ul></li>
7764
7765<li>Return Value:
7766
7767<ul>
7768
7769<li>a <tt>boolean</tt> on whether the argument is an <tt>array</tt> value or not,</li>
7770
7771<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
7772
7773<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
7774 </ul></li>
7775
7776<li>
7777<p>Example:</p>
7778
7779<div class="source">
7780<div class="source">
7781<pre>{
7782 &quot;a&quot;: is_array(true),
7783 &quot;b&quot;: is_array(false),
7784 &quot;c&quot;: isarray(null),
7785 &quot;d&quot;: isarray(missing),
7786 &quot;e&quot;: isarray(&quot;d&quot;),
7787 &quot;f&quot;: isarray(4.0),
7788 &quot;g&quot;: isarray(5),
7789 &quot;h&quot;: isarray([&quot;1&quot;, 2]),
7790 &quot;i&quot;: isarray({&quot;a&quot;:1})
7791};
7792</pre></div></div></li>
7793</ul>
7794
7795<ul>
7796
7797<li>
7798<p>The expected result is:</p>
7799
7800<div class="source">
7801<div class="source">
7802<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 }
7803</pre></div></div></li>
7804</ul>
7805<p>The function has an alias <tt>isarray</tt>.</p></div>
7806<div class="section">
7807<h3><a name="is_boolean_isboolean_isbool"></a>is_boolean (isboolean, isbool)</h3>
7808
7809<ul>
7810
7811<li>
7812<p>Syntax:</p>
7813
7814<div class="source">
7815<div class="source">
7816<pre>is_boolean(expr)
7817</pre></div></div></li>
7818
7819<li>
7820<p>Checks whether the given expression is evaluated to be a <tt>boolean</tt> value.</p></li>
7821
7822<li>Arguments:
7823
7824<ul>
7825
7826<li><tt>expr</tt> : an expression (any type is allowed).</li>
7827 </ul></li>
7828
7829<li>Return Value:
7830
7831<ul>
7832
7833<li>a <tt>boolean</tt> on whether the argument is a <tt>boolean</tt> value or not,</li>
7834
7835<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
7836
7837<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
7838 </ul></li>
7839
7840<li>
7841<p>Example:</p>
7842
7843<div class="source">
7844<div class="source">
7845<pre>{
7846 &quot;a&quot;: isboolean(true),
7847 &quot;b&quot;: isboolean(false),
7848 &quot;c&quot;: is_boolean(null),
7849 &quot;d&quot;: is_boolean(missing),
7850 &quot;e&quot;: isbool(&quot;d&quot;),
7851 &quot;f&quot;: isbool(4.0),
7852 &quot;g&quot;: isbool(5),
7853 &quot;h&quot;: isbool([&quot;1&quot;, 2]),
7854 &quot;i&quot;: isbool({&quot;a&quot;:1})
7855};
7856</pre></div></div></li>
7857</ul>
7858
7859<ul>
7860
7861<li>
7862<p>The expected result is:</p>
7863
7864<div class="source">
7865<div class="source">
7866<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 }
7867</pre></div></div></li>
7868</ul>
7869<p>The function has two aliases, <tt>isboolean</tt> or <tt>isbool</tt>.</p></div>
7870<div class="section">
7871<h3><a name="is_number_isnumber_isnum"></a>is_number (isnumber, isnum)</h3>
7872
7873<ul>
7874
7875<li>
7876<p>Syntax:</p>
7877
7878<div class="source">
7879<div class="source">
7880<pre>is_number(expr)
7881</pre></div></div></li>
7882
7883<li>
7884<p>Checks whether the given expression is evaluated to be a numeric value.</p></li>
7885
7886<li>Arguments:
7887
7888<ul>
7889
7890<li><tt>expr</tt> : an expression (any type is allowed).</li>
7891 </ul></li>
7892
7893<li>Return Value:
7894
7895<ul>
7896
7897<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>
7898
7899<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
7900
7901<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
7902 </ul></li>
7903
7904<li>
7905<p>Example:</p>
7906
7907<div class="source">
7908<div class="source">
7909<pre>{
7910 &quot;a&quot;: is_number(true),
7911 &quot;b&quot;: is_number(false),
7912 &quot;c&quot;: isnumber(null),
7913 &quot;d&quot;: isnumber(missing),
7914 &quot;e&quot;: isnumber(&quot;d&quot;),
7915 &quot;f&quot;: isnum(4.0),
7916 &quot;g&quot;: isnum(5),
7917 &quot;h&quot;: isnum([&quot;1&quot;, 2]),
7918 &quot;i&quot;: isnum({&quot;a&quot;:1})
7919};
7920</pre></div></div></li>
7921</ul>
7922
7923<ul>
7924
7925<li>
7926<p>The expected result is:</p>
7927
7928<div class="source">
7929<div class="source">
7930<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 }
7931</pre></div></div></li>
7932</ul>
7933<p>The function has two aliases, <tt>isnumber</tt> or <tt>isnum</tt>.</p></div>
7934<div class="section">
7935<h3><a name="is_object_isobject_isobj"></a>is_object (isobject, isobj)</h3>
7936
7937<ul>
7938
7939<li>
7940<p>Syntax:</p>
7941
7942<div class="source">
7943<div class="source">
7944<pre>is_object(expr)
7945</pre></div></div></li>
7946
7947<li>
7948<p>Checks whether the given expression is evaluated to be a <tt>object</tt> value.</p></li>
7949
7950<li>Arguments:
7951
7952<ul>
7953
7954<li><tt>expr</tt> : an expression (any type is allowed).</li>
7955 </ul></li>
7956
7957<li>Return Value:
7958
7959<ul>
7960
7961<li>a <tt>boolean</tt> on whether the argument is a <tt>object</tt> value or not,</li>
7962
7963<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
7964
7965<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
7966 </ul></li>
7967
7968<li>
7969<p>Example:</p>
7970
7971<div class="source">
7972<div class="source">
7973<pre>{
7974 &quot;a&quot;: is_object(true),
7975 &quot;b&quot;: is_object(false),
7976 &quot;c&quot;: isobject(null),
7977 &quot;d&quot;: isobject(missing),
7978 &quot;e&quot;: isobj(&quot;d&quot;),
7979 &quot;f&quot;: isobj(4.0),
7980 &quot;g&quot;: isobj(5),
7981 &quot;h&quot;: isobj([&quot;1&quot;, 2]),
7982 &quot;i&quot;: isobj({&quot;a&quot;:1})
7983};
7984</pre></div></div></li>
7985</ul>
7986
7987<ul>
7988
7989<li>
7990<p>The expected result is:</p>
7991<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>
7992</ul>
7993<p>The function has two aliases, <tt>isobject</tt> or <tt>isobj</tt>.</p></div>
7994<div class="section">
7995<h3><a name="is_string_isstring_isstr"></a>is_string (isstring, isstr)</h3>
7996
7997<ul>
7998
7999<li>
8000<p>Syntax:</p>
8001
8002<div class="source">
8003<div class="source">
8004<pre>is_string(expr)
8005</pre></div></div></li>
8006
8007<li>
8008<p>Checks whether the given expression is evaluated to be a <tt>string</tt> value.</p></li>
8009
8010<li>Arguments:
8011
8012<ul>
8013
8014<li><tt>expr</tt> : an expression (any type is allowed).</li>
8015 </ul></li>
8016
8017<li>Return Value:
8018
8019<ul>
8020
8021<li>a <tt>boolean</tt> on whether the argument is a <tt>string</tt> value or not,</li>
8022
8023<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
8024
8025<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
8026 </ul></li>
8027
8028<li>
8029<p>Example:</p>
8030
8031<div class="source">
8032<div class="source">
8033<pre>{
8034 &quot;a&quot;: is_string(true),
8035 &quot;b&quot;: isstring(false),
8036 &quot;c&quot;: isstring(null),
8037 &quot;d&quot;: isstr(missing),
8038 &quot;e&quot;: isstr(&quot;d&quot;),
8039 &quot;f&quot;: isstr(4.0),
8040 &quot;g&quot;: isstr(5),
8041 &quot;h&quot;: isstr([&quot;1&quot;, 2]),
8042 &quot;i&quot;: isstr({&quot;a&quot;:1})
8043};
8044</pre></div></div></li>
8045</ul>
8046
8047<ul>
8048
8049<li>
8050<p>The expected result is:</p>
8051
8052<div class="source">
8053<div class="source">
8054<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 }
8055</pre></div></div></li>
8056</ul>
8057<p>The function has two aliases, <tt>isstring</tt> or <tt>isstr</tt>.</p></div>
8058<div class="section">
8059<h3><a name="is_null"></a>is_null</h3>
8060
8061<ul>
8062
8063<li>
8064<p>Syntax:</p>
8065
8066<div class="source">
8067<div class="source">
8068<pre>is_null(expr)
8069</pre></div></div></li>
8070
8071<li>
8072<p>Checks whether the given expression is evaluated to be a <tt>null</tt> value.</p></li>
8073
8074<li>Arguments:
8075
8076<ul>
8077
8078<li><tt>expr</tt> : an expression (any type is allowed).</li>
8079 </ul></li>
8080
8081<li>Return Value:
8082
8083<ul>
8084
8085<li>a <tt>boolean</tt> on whether the variable is a <tt>null</tt> or not,</li>
8086
8087<li>a <tt>missing</tt> if the input is <tt>missing</tt>.</li>
8088 </ul></li>
8089
8090<li>
8091<p>Example:</p>
8092
8093<div class="source">
8094<div class="source">
8095<pre>{ &quot;v1&quot;: is_null(null), &quot;v2&quot;: is_null(1), &quot;v3&quot;: is_null(missing) };
8096</pre></div></div></li>
8097</ul>
8098
8099<ul>
8100
8101<li>
8102<p>The expected result is:</p>
8103
8104<div class="source">
8105<div class="source">
8106<pre>{ &quot;v1&quot;: true, &quot;v2&quot;: false }
8107</pre></div></div></li>
8108</ul>
8109<p>The function has an alias <tt>isnull</tt>.</p></div>
8110<div class="section">
8111<h3><a name="is_missing"></a>is_missing</h3>
8112
8113<ul>
8114
8115<li>
8116<p>Syntax:</p>
8117
8118<div class="source">
8119<div class="source">
8120<pre>is_missing(expr)
8121</pre></div></div></li>
8122
8123<li>
8124<p>Checks whether the given expression is evaluated to be a <tt>missing</tt> value.</p></li>
8125
8126<li>Arguments:
8127
8128<ul>
8129
8130<li><tt>expr</tt> : an expression (any type is allowed).</li>
8131 </ul></li>
8132
8133<li>Return Value:
8134
8135<ul>
8136
8137<li>a <tt>boolean</tt> on whether the variable is a <tt>missing</tt> or not.</li>
8138 </ul></li>
8139
8140<li>
8141<p>Example:</p>
8142
8143<div class="source">
8144<div class="source">
8145<pre>{ &quot;v1&quot;: is_missing(null), &quot;v2&quot;: is_missing(1), &quot;v3&quot;: is_missing(missing) };
8146</pre></div></div></li>
8147</ul>
8148
8149<ul>
8150
8151<li>
8152<p>The expected result is:</p>
8153
8154<div class="source">
8155<div class="source">
8156<pre>{ &quot;v1&quot;: false, &quot;v2&quot;: false, &quot;v3&quot;: true }
8157</pre></div></div></li>
8158</ul>
8159<p>The function has an alias <tt>ismissing</tt>.</p></div>
8160<div class="section">
8161<h3><a name="is_unknown"></a>is_unknown</h3>
8162
8163<ul>
8164
8165<li>
8166<p>Syntax:</p>
8167
8168<div class="source">
8169<div class="source">
8170<pre>is_unknown(expr)
8171</pre></div></div></li>
8172
8173<li>
8174<p>Checks whether the given variable is a <tt>null</tt> value or a <tt>missing</tt> value.</p></li>
8175
8176<li>Arguments:
8177
8178<ul>
8179
8180<li><tt>expr</tt> : an expression (any type is allowed).</li>
8181 </ul></li>
8182
8183<li>Return Value:
8184
8185<ul>
8186
8187<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>
8188 </ul></li>
8189
8190<li>
8191<p>Example:</p>
8192
8193<div class="source">
8194<div class="source">
8195<pre>{ &quot;v1&quot;: is_unknown(null), &quot;v2&quot;: is_unknown(1), &quot;v3&quot;: is_unknown(missing) };
8196</pre></div></div></li>
8197</ul>
8198
8199<ul>
8200
8201<li>
8202<p>The expected result is:</p>
8203
8204<div class="source">
8205<div class="source">
8206<pre>{ &quot;v1&quot;: true, &quot;v2&quot;: false, &quot;v3&quot;: true }
8207</pre></div></div></li>
8208</ul>
8209<p>The function has an alias <tt>isunknown</tt>.</p>
8210<!-- ! Licensed to the Apache Software Foundation (ASF) under one
8211 ! or more contributor license agreements. See the NOTICE file
8212 ! distributed with this work for additional information
8213 ! regarding copyright ownership. The ASF licenses this file
8214 ! to you under the Apache License, Version 2.0 (the
8215 ! "License"); you may not use this file except in compliance
8216 ! with the License. You may obtain a copy of the License at
8217 !
8218 ! http://www.apache.org/licenses/LICENSE-2.0
8219 !
8220 ! Unless required by applicable law or agreed to in writing,
8221 ! software distributed under the License is distributed on an
8222 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
8223 ! KIND, either express or implied. See the License for the
8224 ! specific language governing permissions and limitations
8225 ! under the License.
8226 ! --></div></div>
8227<div class="section">
8228<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>
8229<div class="section">
8230<h3><a name="uuid"></a>uuid</h3>
8231
8232<ul>
8233
8234<li>
8235<p>Syntax:</p>
8236
8237<div class="source">
8238<div class="source">
8239<pre>uuid()
8240</pre></div></div></li>
8241
8242<li>
8243<p>Generates a <tt>uuid</tt>.</p></li>
8244
8245<li>Arguments:
8246
8247<ul>
8248
8249<li>none</li>
8250 </ul></li>
8251
8252<li>Return Value:
8253
8254<ul>
8255
8256<li>a generated, random <tt>uuid</tt>.</li>
8257 </ul></li>
8258</ul></div>
8259<div class="section">
8260<h3><a name="len"></a>len</h3>
8261
8262<ul>
8263
8264<li>
8265<p>Syntax:</p>
8266<p>len(array)</p></li>
8267
8268<li>
8269<p>Returns the length of the array array.</p></li>
8270
8271<li>Arguments:
8272
8273<ul>
8274
8275<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>
8276 </ul></li>
8277
8278<li>Return Value:
8279
8280<ul>
8281
8282<li>an <tt>integer</tt> that represents the length of input array or the size of the input multiset,</li>
8283
8284<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
8285
8286<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value.</li>
8287 </ul></li>
8288
8289<li>
8290<p>Example:</p>
8291
8292<div class="source">
8293<div class="source">
8294<pre>len([&quot;Hello&quot;, &quot;World&quot;])
8295</pre></div></div></li>
8296</ul>
8297
8298<ul>
8299
8300<li>
8301<p>The expected result is:</p>
8302
8303<div class="source">
8304<div class="source">
8305<pre>2
8306</pre></div></div></li>
8307</ul></div>
8308<div class="section">
8309<h3><a name="not"></a>not</h3>
8310
8311<ul>
8312
8313<li>
8314<p>Syntax:</p>
8315
8316<div class="source">
8317<div class="source">
8318<pre>not(expr)
8319</pre></div></div></li>
8320
8321<li>
8322<p>Inverts a <tt>boolean</tt> value</p></li>
8323
8324<li>Arguments:
8325
8326<ul>
8327
8328<li><tt>expr</tt> : an expression</li>
8329 </ul></li>
8330
8331<li>Return Value:
8332
8333<ul>
8334
8335<li>a <tt>boolean</tt>, the inverse of <tt>expr</tt>,</li>
8336
8337<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
8338
8339<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
8340
8341<li>other non-boolean argument value will cause a type error.</li>
8342 </ul></li>
8343
8344<li>
8345<p>Example:</p>
8346
8347<div class="source">
8348<div class="source">
8349<pre>{ &quot;v1&quot;: `not`(true), &quot;v2&quot;: `not`(false), &quot;v3&quot;: `not`(null), &quot;v4&quot;: `not`(missing) };
8350</pre></div></div></li>
8351
8352<li>
8353<p>The expected result is:</p>
8354
8355<div class="source">
8356<div class="source">
8357<pre>{ &quot;v1&quot;: false, &quot;v2&quot;: true, &quot;v3&quot;: null }
8358</pre></div></div></li>
8359</ul></div>
8360<div class="section">
8361<h3><a name="range"></a>range</h3>
8362
8363<ul>
8364
8365<li>
8366<p>Syntax:</p>
8367
8368<div class="source">
8369<div class="source">
8370<pre>range(start_numeric_value, end_numeric_value)
8371</pre></div></div></li>
8372
8373<li>
8374<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>
8375
8376<li>Arguments:</li>
8377
8378<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>
8379
8380<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>
8381
8382<li>Return Value:
8383
8384<ul>
8385
8386<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>
8387 </ul></li>
8388
8389<li>
8390<p>Example:</p>
8391
8392<div class="source">
8393<div class="source">
8394<pre>range(0, 3);
8395</pre></div></div></li>
8396
8397<li>
8398<p>The expected result is:</p>
8399
8400<div class="source">
8401<div class="source">
8402<pre>[ 0, 1, 2, 3 ]
8403</pre></div></div></li>
8404</ul></div>
8405<div class="section">
8406<h3><a name="switch_case"></a>switch_case</h3>
8407
8408<ul>
8409
8410<li>
8411<p>Syntax:</p>
8412
8413<div class="source">
8414<div class="source">
8415<pre>switch_case(
8416 condition,
8417 case1, case1_result,
8418 case2, case2_result,
8419 ...,
8420 default, default_result
8421)
8422</pre></div></div></li>
8423
8424<li>
8425<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>
8426
8427<li>Arguments:
8428
8429<ul>
8430
8431<li><tt>condition</tt>: a variable (any type is allowed).</li>
8432
8433<li><tt>caseI/default</tt>: a variable (any type is allowed).</li>
8434
8435<li><tt>caseI/default_result</tt>: a variable (any type is allowed).</li>
8436 </ul></li>
8437
8438<li>Return Value:
8439
8440<ul>
8441
8442<li><tt>caseI_result</tt> if <tt>condition</tt> matches <tt>caseI</tt>, otherwise <tt>default_result</tt>.</li>
8443 </ul></li>
8444
8445<li>
8446<p>Example 1:</p>
8447
8448<div class="source">
8449<div class="source">
8450<pre>switch_case(
8451 &quot;a&quot;,
8452 &quot;a&quot;, 0,
8453 &quot;x&quot;, 1,
8454 &quot;y&quot;, 2,
8455 &quot;z&quot;, 3
8456);
8457</pre></div></div></li>
8458</ul>
8459
8460<ul>
8461
8462<li>
8463<p>The expected result is:</p>
8464
8465<div class="source">
8466<div class="source">
8467<pre>0
8468</pre></div></div></li>
8469
8470<li>
8471<p>Example 2:</p>
8472
8473<div class="source">
8474<div class="source">
8475<pre>switch_case(
8476 &quot;a&quot;,
8477 &quot;x&quot;, 1,
8478 &quot;y&quot;, 2,
8479 &quot;z&quot;, 3
8480);
8481</pre></div></div></li>
8482
8483<li>
8484<p>The expected result is:</p>
8485
8486<div class="source">
8487<div class="source">
8488<pre>3
8489</pre></div></div></li>
8490</ul></div>
8491<div class="section">
8492<h3><a name="deep_equal"></a>deep_equal</h3>
8493
8494<ul>
8495
8496<li>
8497<p>Syntax:</p>
8498
8499<div class="source">
8500<div class="source">
8501<pre>deep_equal(expr1, expr2)
8502</pre></div></div></li>
8503</ul>
8504
8505<ul>
8506
8507<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>
8508
8509<li>Arguments:
8510
8511<ul>
8512
8513<li><tt>expr1</tt> : an expression,</li>
8514
8515<li><tt>expr2</tt> : an expression.</li>
8516 </ul></li>
8517
8518<li>Return Value:
8519
8520<ul>
8521
8522<li><tt>true</tt> or <tt>false</tt> depending on the data equality,</li>
8523
8524<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
8525
8526<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value.</li>
8527 </ul></li>
8528</ul>
8529
8530<ul>
8531
8532<li>
8533<p>Example:</p>
8534
8535<div class="source">
8536<div class="source">
8537<pre>deep_equal(
8538 {
8539 &quot;id&quot;:1,
8540 &quot;project&quot;:&quot;AsterixDB&quot;,
8541 &quot;address&quot;:{&quot;city&quot;:&quot;Irvine&quot;, &quot;state&quot;:&quot;CA&quot;},
8542 &quot;related&quot;:[&quot;Hivestrix&quot;, &quot;Preglix&quot;, &quot;Apache VXQuery&quot;]
8543 },
8544 {
8545 &quot;id&quot;:1,
8546 &quot;project&quot;:&quot;AsterixDB&quot;,
8547 &quot;address&quot;:{&quot;city&quot;:&quot;San Diego&quot;, &quot;state&quot;:&quot;CA&quot;},
8548 &quot;related&quot;:[&quot;Hivestrix&quot;, &quot;Preglix&quot;, &quot;Apache VXQuery&quot;]
8549 }
8550);
8551</pre></div></div></li>
8552
8553<li>
8554<p>The expected result is:</p>
8555
8556<div class="source">
8557<div class="source">
8558<pre>false
8559</pre></div></div></li>
8560</ul></div></div>
8561 </div>
8562 </div>
8563 </div>
8564
8565 <hr/>
8566
8567 <footer>
8568 <div class="container-fluid">
8569 <div class="row span12">Copyright &copy; 2017
8570 <a href="https://www.apache.org/">The Apache Software Foundation</a>.
8571 All Rights Reserved.
8572
8573 </div>
8574
8575 <?xml version="1.0" encoding="UTF-8"?>
8576<div class="row-fluid">Apache AsterixDB, AsterixDB, Apache, the Apache
8577 feather logo, and the Apache AsterixDB project logo are either
8578 registered trademarks or trademarks of The Apache Software
8579 Foundation in the United States and other countries.
8580 All other marks mentioned may be trademarks or registered
8581 trademarks of their respective owners.</div>
8582
8583
8584 </div>
8585 </footer>
8586 </body>
8587</html>