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