Gitiles
Code Review Sign In
asterix-gerrit.ics.uci.edu / incubator-asterixdb-site / 340445830e94147ab24a8ca38dd91710ee172981 / . / content / docs / 0.9.8 / sqlpp / builtins.html
blob: da5f5e511d5628d71d2fd0026b0b704d8a807adb [file] [log] [blame]
Ian Maxon858061a2022-05-12 19:11:28 -0700[diff] [blame]1<!DOCTYPE html>
2<!--
3 | Generated by Apache Maven Doxia Site Renderer 1.8.1 from target/generated-site/markdown/sqlpp/builtins.md at 2022-05-12
4 | Rendered using Apache Maven Fluido Skin 1.7
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="20220512" />
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.7.min.css" />
14 <link rel="stylesheet" href="../css/site.css" />
15 <link rel="stylesheet" href="../css/print.css" media="print" />
16 <script type="text/javascript" src="../js/apache-maven-fluido-1.7.min.js"></script>
17
18 </head>
19 <body class="topBarDisabled">
20 <div class="container-fluid">
21 <div id="banner">
22 <div class="pull-left"><a href=".././" id="bannerLeft"><img src="../images/asterixlogo.png" alt="AsterixDB"/></a></div>
23 <div class="pull-right"></div>
24 <div class="clear"><hr/></div>
25 </div>
26
27 <div id="breadcrumbs">
28 <ul class="breadcrumb">
29 <li id="publishDate">Last Published: 2022-05-12</li>
30 <li id="projectVersion" class="pull-right">Version: 0.9.8</li>
31 <li class="pull-right"><a href="../index.html" title="Documentation Home">Documentation Home</a></li>
32 </ul>
33 </div>
34 <div class="row-fluid">
35 <div id="leftColumn" class="span2">
36 <div class="well sidebar-nav">
37 <ul class="nav nav-list">
38 <li class="nav-header">Get Started - Installation</li>
39 <li><a href="../ncservice.html" title="Option 1: using NCService"><span class="none"></span>Option 1: using NCService</a></li>
40 <li><a href="../ansible.html" title="Option 2: using Ansible"><span class="none"></span>Option 2: using Ansible</a></li>
41 <li><a href="../aws.html" title="Option 3: using Amazon Web Services"><span class="none"></span>Option 3: using Amazon Web Services</a></li>
42 <li class="nav-header">AsterixDB Primer</li>
43 <li><a href="../sqlpp/primer-sqlpp.html" title="Using SQL++"><span class="none"></span>Using SQL++</a></li>
44 <li class="nav-header">Data Model</li>
45 <li><a href="../datamodel.html" title="The Asterix Data Model"><span class="none"></span>The Asterix Data Model</a></li>
46 <li class="nav-header">Queries</li>
47 <li><a href="../sqlpp/manual.html" title="The SQL++ Query Language"><span class="none"></span>The SQL++ Query Language</a></li>
48 <li><a href="../SQLPP.html" title="Raw SQL++ Grammar"><span class="none"></span>Raw SQL++ Grammar</a></li>
49 <li class="active"><a href="#"><span class="none"></span>Builtin Functions</a></li>
50 <li class="nav-header">API/SDK</li>
51 <li><a href="../api.html" title="HTTP API"><span class="none"></span>HTTP API</a></li>
52 <li><a href="../csv.html" title="CSV Output"><span class="none"></span>CSV Output</a></li>
53 <li class="nav-header">Advanced Features</li>
54 <li><a href="../aql/externaldata.html" title="Accessing External Data"><span class="none"></span>Accessing External Data</a></li>
55 <li><a href="../feeds.html" title="Data Ingestion with Feeds"><span class="none"></span>Data Ingestion with Feeds</a></li>
56 <li><a href="../udf.html" title="User Defined Functions"><span class="none"></span>User Defined Functions</a></li>
57 <li><a href="../sqlpp/filters.html" title="Filter-Based LSM Index Acceleration"><span class="none"></span>Filter-Based LSM Index Acceleration</a></li>
58 <li><a href="../sqlpp/fulltext.html" title="Support of Full-text Queries"><span class="none"></span>Support of Full-text Queries</a></li>
59 <li><a href="../sqlpp/similarity.html" title="Support of Similarity Queries"><span class="none"></span>Support of Similarity Queries</a></li>
60 <li><a href="../geo/quickstart.html" title="GIS Support Overview"><span class="none"></span>GIS Support Overview</a></li>
61 <li><a href="../geo/functions.html" title="GIS Functions"><span class="none"></span>GIS Functions</a></li>
62 <li><a href="../interval_join.html" title="Support of Interval Joins"><span class="none"></span>Support of Interval Joins</a></li>
63 <li><a href="../spatial_join.html" title="Support of Spatial Joins"><span class="none"></span>Support of Spatial Joins</a></li>
64 <li><a href="../sqlpp/arrayindex.html" title="Support of Array Indexes"><span class="none"></span>Support of Array Indexes</a></li>
65 <li class="nav-header">Deprecated</li>
66 <li><a href="../aql/primer.html" title="AsterixDB Primer: Using AQL"><span class="none"></span>AsterixDB Primer: Using AQL</a></li>
67 <li><a href="../aql/manual.html" title="Queries: The Asterix Query Language (AQL)"><span class="none"></span>Queries: The Asterix Query Language (AQL)</a></li>
68 <li><a href="../aql/builtins.html" title="Queries: Builtin Functions (AQL)"><span class="none"></span>Queries: Builtin Functions (AQL)</a></li>
69</ul>
70 <hr />
71 <div id="poweredBy">
72 <div class="clear"></div>
73 <div class="clear"></div>
74 <div class="clear"></div>
75 <div class="clear"></div>
76<a href=".././" title="AsterixDB" class="builtBy"><img class="builtBy" alt="AsterixDB" src="../images/asterixlogo.png" /></a>
77 </div>
78 </div>
79 </div>
80 <div id="bodyColumn" class="span10" >
81<!--
82 ! Licensed to the Apache Software Foundation (ASF) under one
83 ! or more contributor license agreements. See the NOTICE file
84 ! distributed with this work for additional information
85 ! regarding copyright ownership. The ASF licenses this file
86 ! to you under the Apache License, Version 2.0 (the
87 ! "License"); you may not use this file except in compliance
88 ! with the License. You may obtain a copy of the License at
89 !
90 ! http://www.apache.org/licenses/LICENSE-2.0
91 !
92 ! Unless required by applicable law or agreed to in writing,
93 ! software distributed under the License is distributed on an
94 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
95 ! KIND, either express or implied. See the License for the
96 ! specific language governing permissions and limitations
97 ! under the License.
98 !-->
99<h1>Builtin Functions</h1><!--
100 ! Licensed to the Apache Software Foundation (ASF) under one
101 ! or more contributor license agreements. See the NOTICE file
102 ! distributed with this work for additional information
103 ! regarding copyright ownership. The ASF licenses this file
104 ! to you under the Apache License, Version 2.0 (the
105 ! "License"); you may not use this file except in compliance
106 ! with the License. You may obtain a copy of the License at
107 !
108 ! http://www.apache.org/licenses/LICENSE-2.0
109 !
110 ! Unless required by applicable law or agreed to in writing,
111 ! software distributed under the License is distributed on an
112 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
113 ! KIND, either express or implied. See the License for the
114 ! specific language governing permissions and limitations
115 ! under the License.
116 !-->
117
118<div class="section">
119<h2><a name="Table_of_Contents"></a><a name="toc" id="toc">Table of Contents</a></h2>
120<ul>
121
122<li><a href="#NumericFunctions">Numeric Functions</a></li>
123<li><a href="#StringFunctions">String Functions</a></li>
124<li><a href="#BinaryFunctions">Binary Functions</a></li>
125<li><a href="#SpatialFunctions">Spatial Functions</a></li>
126<li><a href="#SimilarityFunctions">Similarity Functions</a></li>
127<li><a href="#TokenizingFunctions">Tokenizing Functions</a></li>
128<li><a href="#TemporalFunctions">Temporal Functions</a></li>
129<li><a href="#ObjectFunctions">Object Functions</a></li>
130<li><a href="#AggregateFunctions">Aggregate Functions (Array Functions)</a></li>
131<li><a href="#ComparisonFunctions">Comparison Functions</a></li>
132<li><a href="#TypeFunctions">Type Functions</a></li>
133<li><a href="#ConditionalFunctions">Conditional Functions</a></li>
134<li><a href="#MiscFunctions">Miscellaneous Functions</a></li>
135<li><a href="#BitwiseFunctions">Bitwise Functions</a></li>
136<li><a href="#WindowFunctions">Window Functions</a></li>
137</ul><!--
138 ! Licensed to the Apache Software Foundation (ASF) under one
139 ! or more contributor license agreements. See the NOTICE file
140 ! distributed with this work for additional information
141 ! regarding copyright ownership. The ASF licenses this file
142 ! to you under the Apache License, Version 2.0 (the
143 ! "License"); you may not use this file except in compliance
144 ! with the License. You may obtain a copy of the License at
145 !
146 ! http://www.apache.org/licenses/LICENSE-2.0
147 !
148 ! Unless required by applicable law or agreed to in writing,
149 ! software distributed under the License is distributed on an
150 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
151 ! KIND, either express or implied. See the License for the
152 ! specific language governing permissions and limitations
153 ! under the License.
154 !-->
155
156<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.</p><!--
157 ! Licensed to the Apache Software Foundation (ASF) under one
158 ! or more contributor license agreements. See the NOTICE file
159 ! distributed with this work for additional information
160 ! regarding copyright ownership. The ASF licenses this file
161 ! to you under the Apache License, Version 2.0 (the
162 ! "License"); you may not use this file except in compliance
163 ! with the License. You may obtain a copy of the License at
164 !
165 ! http://www.apache.org/licenses/LICENSE-2.0
166 !
167 ! Unless required by applicable law or agreed to in writing,
168 ! software distributed under the License is distributed on an
169 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
170 ! KIND, either express or implied. See the License for the
171 ! specific language governing permissions and limitations
172 ! under the License.
173 !-->
174</div>
175<div class="section">
176<h2><a name="Numeric_Functions"></a><a name="NumericFunctions" id="NumericFunctions">Numeric Functions</a></h2>
177<div class="section">
178<h3><a name="abs"></a>abs</h3>
179<ul>
180
181<li>
182
183<p>Syntax:</p>
184
185<div>
186<div>
187<pre class="source">abs(numeric_value)
188</pre></div></div>
189</li>
190<li>
191
192<p>Computes the absolute value of the argument.</p>
193</li>
194<li>Arguments:
195<ul>
196
197<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>
198</ul>
199</li>
200<li>Return Value:
201<ul>
202
203<li>The absolute value of the argument with the same type as the input argument,</li>
204<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
205<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
206<li>any other non-numeric input value will cause a type error.</li>
207</ul>
208</li>
209<li>
210
211<p>Example:</p>
212
213<div>
214<div>
215<pre class="source">{ &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;)) };
216</pre></div></div>
217</li>
218<li>
219
220<p>The expected result is:</p>
221
222<div>
223<div>
224<pre class="source">{ &quot;v1&quot;: 2013, &quot;v2&quot;: 4036, &quot;v3&quot;: 0, &quot;v4&quot;: 2013.5, &quot;v5&quot;: 2013.5938237483274 }
225</pre></div></div>
226</li>
227</ul></div>
228<div class="section">
229<h3><a name="acos"></a>acos</h3>
230<ul>
231
232<li>
233
234<p>Syntax:</p>
235
236<div>
237<div>
238<pre class="source">acos(numeric_value)
239</pre></div></div>
240</li>
241<li>
242
243<p>Computes the arc cosine value of the argument.</p>
244</li>
245<li>Arguments:
246<ul>
247
248<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>
249</ul>
250</li>
251<li>Return Value:
252<ul>
253
254<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>
255<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
256<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
257<li>any other non-numeric input value will cause a type error,</li>
258<li>&#x201c;NaN&#x201d; for other legitimate numeric values.</li>
259</ul>
260</li>
261<li>
262
263<p>Example:</p>
264
265<div>
266<div>
267<pre class="source">{ &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;)) };
268</pre></div></div>
269</li>
270<li>
271
272<p>The expected result is:</p>
273
274<div>
275<div>
276<pre class="source">{ &quot;v1&quot;: 0.0, &quot;v2&quot;: &quot;NaN&quot;, &quot;v3&quot;: 1.5707963267948966, &quot;v4&quot;: 1.0471975511965979, &quot;v5&quot;: 2.0943951023931957 }
277</pre></div></div>
278</li>
279</ul></div>
280<div class="section">
281<h3><a name="asin"></a>asin</h3>
282<ul>
283
284<li>
285
286<p>Syntax:</p>
287
288<div>
289<div>
290<pre class="source">asin(numeric_value)
291</pre></div></div>
292</li>
293<li>
294
295<p>Computes the arc sine value of the argument.</p>
296</li>
297<li>Arguments:
298<ul>
299
300<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>
301</ul>
302</li>
303<li>Return Value:
304<ul>
305
306<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>
307<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
308<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
309<li>any other non-numeric input value will cause a type error,</li>
310<li>&#x201c;NaN&#x201d; for other legitimate numeric values.</li>
311</ul>
312</li>
313<li>
314
315<p>Example:</p>
316
317<div>
318<div>
319<pre class="source">{ &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;)) };
320</pre></div></div>
321</li>
322<li>
323
324<p>The expected result is:</p>
325
326<div>
327<div>
328<pre class="source">{ &quot;v1&quot;: 1.5707963267948966, &quot;v2&quot;: &quot;NaN&quot;, &quot;v3&quot;: 0.0, &quot;v4&quot;: 0.5235987755982989, &quot;v5&quot;: -0.5235987755982989 }
329</pre></div></div>
330</li>
331</ul></div>
332<div class="section">
333<h3><a name="atan"></a>atan</h3>
334<ul>
335
336<li>
337
338<p>Syntax:</p>
339
340<div>
341<div>
342<pre class="source">atan(numeric_value)
343</pre></div></div>
344</li>
345<li>
346
347<p>Computes the arc tangent value of the argument.</p>
348</li>
349<li>Arguments:
350<ul>
351
352<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>
353</ul>
354</li>
355<li>Return Value:
356<ul>
357
358<li>the <tt>double</tt> arc tangent in radians for the argument,</li>
359<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
360<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
361<li>any other non-numeric input value will cause a type error.</li>
362</ul>
363</li>
364<li>
365
366<p>Example:</p>
367
368<div>
369<div>
370<pre class="source">{ &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;)) };
371</pre></div></div>
372</li>
373<li>
374
375<p>The expected result is:</p>
376
377<div>
378<div>
379<pre class="source">{ &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 }
380</pre></div></div>
381</li>
382</ul></div>
383<div class="section">
384<h3><a name="atan2"></a>atan2</h3>
385<ul>
386
387<li>
388
389<p>Syntax:</p>
390
391<div>
392<div>
393<pre class="source">atan2(numeric_value1, numeric_value2)
394</pre></div></div>
395</li>
396<li>
397
398<p>Computes the arc tangent value of numeric_value2/numeric_value1.</p>
399</li>
400<li>Arguments:
401<ul>
402
403<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>
404<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>
405</ul>
406</li>
407<li>Return Value:
408<ul>
409
410<li>the <tt>double</tt> arc tangent in radians for <tt>numeric_value1</tt> and <tt>numeric_value2</tt>,</li>
411<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
412<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
413<li>any other non-numeric input value will cause a type error.</li>
414</ul>
415</li>
416<li>
417
418<p>Example:</p>
419
420<div>
421<div>
422<pre class="source">{ &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;)) };
423</pre></div></div>
424</li>
425<li>
426
427<p>The expected result is:</p>
428
429<div>
430<div>
431<pre class="source">{ &quot;v1&quot;: 0.4636476090008061, &quot;v2&quot;: 0.0, &quot;v3&quot;: 2.356194490192345 }
432</pre></div></div>
433</li>
434</ul></div>
435<div class="section">
436<h3><a name="ceil"></a>ceil</h3>
437<ul>
438
439<li>
440
441<p>Syntax:</p>
442
443<div>
444<div>
445<pre class="source">ceil(numeric_value)
446</pre></div></div>
447</li>
448<li>
449
450<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>
451</li>
452<li>Arguments:
453<ul>
454
455<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>
456</ul>
457</li>
458<li>Return Value:
459<ul>
460
461<li>The ceiling value for the given number in the same type as the input argument,</li>
462<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
463<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
464<li>any other non-numeric input value will cause a type error.</li>
465</ul>
466</li>
467<li>
468
469<p>Example:</p>
470
471<div>
472<div>
473<pre class="source">{
474 &quot;v1&quot;: ceil(2013),
475 &quot;v2&quot;: ceil(-4036),
476 &quot;v3&quot;: ceil(0.3),
477 &quot;v4&quot;: ceil(float(&quot;-2013.2&quot;)),
478 &quot;v5&quot;: ceil(double(&quot;-2013.893823748327284&quot;))
479};
480</pre></div></div>
481</li>
482<li>
483
484<p>The expected result is:</p>
485
486<div>
487<div>
488<pre class="source">{ &quot;v1&quot;: 2013, &quot;v2&quot;: -4036, &quot;v3&quot;: 1.0, &quot;v4&quot;: -2013.0, &quot;v5&quot;: -2013.0 }
489</pre></div></div>
490</li>
491</ul></div>
492<div class="section">
493<h3><a name="cos"></a>cos</h3>
494<ul>
495
496<li>
497
498<p>Syntax:</p>
499
500<div>
501<div>
502<pre class="source">cos(numeric_value)
503</pre></div></div>
504</li>
505<li>
506
507<p>Computes the cosine value of the argument.</p>
508</li>
509<li>Arguments:
510<ul>
511
512<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>
513</ul>
514</li>
515<li>Return Value:
516<ul>
517
518<li>the <tt>double</tt> cosine value for the argument,</li>
519<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
520<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
521<li>any other non-numeric input value will cause a type error.</li>
522</ul>
523</li>
524<li>
525
526<p>Example:</p>
527
528<div>
529<div>
530<pre class="source">{ &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;)) };
531</pre></div></div>
532</li>
533<li>
534
535<p>The expected result is:</p>
536
537<div>
538<div>
539<pre class="source">{ &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 }
540</pre></div></div>
541</li>
542</ul></div>
543<div class="section">
544<h3><a name="cosh"></a>cosh</h3>
545<ul>
546
547<li>
548
549<p>Syntax:</p>
550
551<div>
552<div>
553<pre class="source">cosh(numeric_value)
554</pre></div></div>
555</li>
556<li>
557
558<p>Computes the hyperbolic cosine value of the argument.</p>
559</li>
560<li>Arguments:
561<ul>
562
563<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>
564</ul>
565</li>
566<li>Return Value:
567<ul>
568
569<li>the <tt>double</tt> hyperbolic cosine value for the argument,</li>
570<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
571<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
572<li>any other non-numeric input value will cause a type error.</li>
573</ul>
574</li>
575<li>
576
577<p>Example:</p>
578
579<div>
580<div>
581<pre class="source">{ &quot;v1&quot;: cosh(1), &quot;v2&quot;: cosh(2), &quot;v3&quot;: cosh(0), &quot;v4&quot;: cosh(float(&quot;0.5&quot;)), &quot;v5&quot;: cosh(double(&quot;8&quot;)) };
582</pre></div></div>
583</li>
584<li>
585
586<p>The expected result is:</p>
587
588<div>
589<div>
590<pre class="source">{ &quot;v1&quot;: 1.5430806348152437, &quot;v2&quot;: 3.7621956910836314, &quot;v3&quot;: 1.0, &quot;v4&quot;: 1.1276259652063807, &quot;v5&quot;: 1490.479161252178 }
591</pre></div></div>
592</li>
593</ul></div>
594<div class="section">
595<h3><a name="degrees"></a>degrees</h3>
596<ul>
597
598<li>
599
600<p>Syntax:</p>
601
602<div>
603<div>
604<pre class="source">degrees(numeric_value)
605</pre></div></div>
606</li>
607<li>
608
609<p>Converts radians to degrees</p>
610</li>
611<li>Arguments:
612<ul>
613
614<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>
615</ul>
616</li>
617<li>Return Value:
618<ul>
619
620<li>The degrees value for the given radians value. The returned value has type <tt>double</tt>,</li>
621<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
622<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
623<li>any other non-numeric input value will cause a type error.</li>
624</ul>
625</li>
626<li>
627
628<p>Example:</p>
629
630<div>
631<div>
632<pre class="source">{ &quot;v1&quot;: degrees(pi()) };
633</pre></div></div>
634</li>
635<li>
636
637<p>The expected result is:</p>
638
639<div>
640<div>
641<pre class="source">{ &quot;v1&quot;: 180.0 }
642</pre></div></div>
643</li>
644</ul></div>
645<div class="section">
646<h3><a name="e"></a>e</h3>
647<ul>
648
649<li>
650
651<p>Syntax:</p>
652
653<div>
654<div>
655<pre class="source">e()
656</pre></div></div>
657</li>
658<li>
659
660<p>Return Value:</p>
661<ul>
662
663<li>e (base of the natural logarithm)</li>
664</ul>
665</li>
666<li>
667
668<p>Example:</p>
669
670<div>
671<div>
672<pre class="source">{ &quot;v1&quot;: e() };
673</pre></div></div>
674</li>
675<li>
676
677<p>The expected result is:</p>
678
679<div>
680<div>
681<pre class="source">{ &quot;v1&quot;: 2.718281828459045 }
682</pre></div></div>
683</li>
684</ul></div>
685<div class="section">
686<h3><a name="exp"></a>exp</h3>
687<ul>
688
689<li>
690
691<p>Syntax:</p>
692
693<div>
694<div>
695<pre class="source">exp(numeric_value)
696</pre></div></div>
697</li>
698<li>
699
700<p>Computes e<sup>numeric_value</sup>.</p>
701</li>
702<li>Arguments:
703<ul>
704
705<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>
706</ul>
707</li>
708<li>Return Value:
709<ul>
710
711<li>e<sup>numeric_value</sup>,</li>
712<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
713<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
714<li>any other non-numeric input value will cause a type error.</li>
715</ul>
716</li>
717<li>
718
719<p>Example:</p>
720
721<div>
722<div>
723<pre class="source">{ &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;)) };
724</pre></div></div>
725</li>
726<li>
727
728<p>The expected result is:</p>
729
730<div>
731<div>
732<pre class="source">{ &quot;v1&quot;: 2.718281828459045, &quot;v2&quot;: 7.38905609893065, &quot;v3&quot;: 1.0, &quot;v4&quot;: 1.6487212707001282, &quot;v5&quot;: &quot;Infinity&quot; }
733</pre></div></div>
734</li>
735</ul></div>
736<div class="section">
737<h3><a name="floor"></a>floor</h3>
738<ul>
739
740<li>
741
742<p>Syntax:</p>
743
744<div>
745<div>
746<pre class="source">floor(numeric_value)
747</pre></div></div>
748</li>
749<li>
750
751<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>
752</li>
753<li>Arguments:
754<ul>
755
756<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>
757</ul>
758</li>
759<li>Return Value:
760<ul>
761
762<li>The floor value for the given number in the same type as the input argument,</li>
763<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
764<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
765<li>any other non-numeric input value will cause a type error.</li>
766</ul>
767</li>
768<li>
769
770<p>Example:</p>
771
772<div>
773<div>
774<pre class="source">{
775 &quot;v1&quot;: floor(2013),
776 &quot;v2&quot;: floor(-4036),
777 &quot;v3&quot;: floor(0.8),
778 &quot;v4&quot;: floor(float(&quot;-2013.2&quot;)),
779 &quot;v5&quot;: floor(double(&quot;-2013.893823748327284&quot;))
780};
781</pre></div></div>
782</li>
783<li>
784
785<p>The expected result is:</p>
786
787<div>
788<div>
789<pre class="source">{ &quot;v1&quot;: 2013, &quot;v2&quot;: -4036, &quot;v3&quot;: 0.0, &quot;v4&quot;: -2014.0, &quot;v5&quot;: -2014.0 }
790</pre></div></div>
791</li>
792</ul></div>
793<div class="section">
794<h3><a name="ln"></a>ln</h3>
795<ul>
796
797<li>
798
799<p>Syntax:</p>
800
801<div>
802<div>
803<pre class="source">ln(numeric_value)
804</pre></div></div>
805</li>
806<li>
807
808<p>Computes log<sub>e</sub>numeric_value.</p>
809</li>
810<li>Arguments:
811<ul>
812
813<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>
814</ul>
815</li>
816<li>Return Value:
817<ul>
818
819<li>log<sub>e</sub>numeric_value,</li>
820<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
821<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
822<li>any other non-numeric input value will cause a type error.</li>
823</ul>
824</li>
825<li>
826
827<p>Example:</p>
828
829<div>
830<div>
831<pre class="source">{ &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;)) };
832</pre></div></div>
833</li>
834<li>
835
836<p>The expected result is:</p>
837
838<div>
839<div>
840<pre class="source">{ &quot;v1&quot;: 0.0, &quot;v2&quot;: 0.6931471805599453, &quot;v3&quot;: &quot;-Infinity&quot;, &quot;v4&quot;: -0.6931471805599453, &quot;v5&quot;: 6.907755278982137 }
841</pre></div></div>
842</li>
843</ul></div>
844<div class="section">
845<h3><a name="log"></a>log</h3>
846<ul>
847
848<li>
849
850<p>Syntax:</p>
851
852<div>
853<div>
854<pre class="source">log(numeric_value)
855</pre></div></div>
856</li>
857<li>
858
859<p>Computes log<sub>10</sub>numeric_value.</p>
860</li>
861<li>Arguments:
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>
866</li>
867<li>Return Value:
868<ul>
869
870<li>log<sub>10</sub>numeric_value,</li>
871<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
872<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
873<li>any other non-numeric input value will cause a type error.</li>
874</ul>
875</li>
876<li>
877
878<p>Example:</p>
879
880<div>
881<div>
882<pre class="source">{ &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;)) };
883</pre></div></div>
884</li>
885<li>
886
887<p>The expected result is:</p>
888
889<div>
890<div>
891<pre class="source">{ &quot;v1&quot;: 0.0, &quot;v2&quot;: 0.3010299956639812, &quot;v3&quot;: &quot;-Infinity&quot;, &quot;v4&quot;: -0.3010299956639812, &quot;v5&quot;: 3.0 }
892</pre></div></div>
893</li>
894</ul></div>
895<div class="section">
896<h3><a name="pi"></a>pi</h3>
897<ul>
898
899<li>
900
901<p>Syntax:</p>
902
903<div>
904<div>
905<pre class="source">pi()
906</pre></div></div>
907</li>
908<li>
909
910<p>Return Value:</p>
911<ul>
912
913<li>Pi</li>
914</ul>
915</li>
916<li>
917
918<p>Example:</p>
919
920<div>
921<div>
922<pre class="source">{ &quot;v1&quot;: pi() };
923</pre></div></div>
924</li>
925<li>
926
927<p>The expected result is:</p>
928
929<div>
930<div>
931<pre class="source">{ &quot;v1&quot;: 3.141592653589793 }
932</pre></div></div>
933</li>
934</ul></div>
935<div class="section">
936<h3><a name="power"></a>power</h3>
937<ul>
938
939<li>
940
941<p>Syntax:</p>
942
943<div>
944<div>
945<pre class="source">power(numeric_value1, numeric_value2)
946</pre></div></div>
947</li>
948<li>
949
950<p>Computes numeric_value1<sup>numeric_value2</sup>.</p>
951</li>
952<li>Arguments:
953<ul>
954
955<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>
956<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>
957</ul>
958</li>
959<li>Return Value:
960<ul>
961
962<li>numeric_value1<sup>numeric_value2</sup>,</li>
963<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
964<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
965<li>any other non-numeric input value will cause a type error.</li>
966</ul>
967</li>
968<li>
969
970<p>Example:</p>
971
972<div>
973<div>
974<pre class="source">{ &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;)) };
975</pre></div></div>
976</li>
977<li>
978
979<p>The expected result is:</p>
980
981<div>
982<div>
983<pre class="source">{ &quot;v1&quot;: 1, &quot;v3&quot;: 0, &quot;v4&quot;: 1.4142135623730951 }
984</pre></div></div>
985</li>
986</ul></div>
987<div class="section">
988<h3><a name="radians"></a>radians</h3>
989<ul>
990
991<li>
992
993<p>Syntax:</p>
994
995<div>
996<div>
997<pre class="source">radians(numeric_value)
998</pre></div></div>
999</li>
1000<li>
1001
1002<p>Converts degrees to radians</p>
1003</li>
1004<li>Arguments:
1005<ul>
1006
1007<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>
1008</ul>
1009</li>
1010<li>Return Value:
1011<ul>
1012
1013<li>The radians value for the given degrees value. The returned value has type <tt>double</tt>,</li>
1014<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
1015<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
1016<li>any other non-numeric input value will cause a type error.</li>
1017</ul>
1018</li>
1019<li>
1020
1021<p>Example:</p>
1022
1023<div>
1024<div>
1025<pre class="source">{ &quot;v1&quot;: radians(180) };
1026</pre></div></div>
1027</li>
1028<li>
1029
1030<p>The expected result is:</p>
1031
1032<div>
1033<div>
1034<pre class="source">{ &quot;v1&quot;: 3.141592653589793 }
1035</pre></div></div>
1036</li>
1037</ul></div>
1038<div class="section">
1039<h3><a name="round"></a>round</h3>
1040<ul>
1041
1042<li>
1043
1044<p>Syntax:</p>
1045
1046<div>
1047<div>
1048<pre class="source">round(numeric_value[, round_digit])
1049</pre></div></div>
1050</li>
1051<li>
1052
1053<p>Rounds the value to the given number of integer digits to the right of the decimal point, or to the left of the decimal point if the number of digits is negative.</p>
1054</li>
1055<li>
1056
1057<p>Arguments:</p>
1058<ul>
1059
1060<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 that represents the numeric value to be rounded.</li>
1061<li><tt>round_digit</tt>: (Optional) a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value that specifies the digit to round to. This argument may be positive or negative; positive indicating that rounding needs to be to the right of the decimal point, and negative indicating that rounding needs to be to the left of the decimal point. Values such as 1.0 and 2.0 are acceptable, but values such as 1.3 and 1.5 result in a <tt>null</tt>. If omitted, the default is 0.</li>
1062</ul>
1063</li>
1064<li>Return Value:
1065<ul>
1066
1067<li>The rounded value for the given number. The returned value has the following type:
1068<ul>
1069
1070<li><tt>bigint</tt> if the input value has type <tt>tinyint</tt>, <tt>smallint</tt>, <tt>integer</tt> or <tt>bigint</tt>,</li>
1071<li><tt>float</tt> if the input value has type <tt>float</tt>,</li>
1072<li><tt>double</tt> if the input value has type <tt>double</tt>;</li>
1073</ul>
1074</li>
1075<li><tt>missing</tt> if the input value is a <tt>missing</tt> value,</li>
1076<li><tt>null</tt> if the input value is a <tt>null</tt> value,</li>
1077<li>any other non-numeric input value will return a <tt>null</tt> value.</li>
1078</ul>
1079</li>
1080<li>
1081
1082<p>Example:</p>
1083
1084<div>
1085<div>
1086<pre class="source">{
1087 &quot;v1&quot;: round(2013),
1088 &quot;v2&quot;: round(-4036),
1089 &quot;v3&quot;: round(0.8),
1090 &quot;v4&quot;: round(float(&quot;-2013.256&quot;)),
1091 &quot;v5&quot;: round(double(&quot;-2013.893823748327284&quot;))
1092 &quot;v6&quot;: round(123456, -1),
1093 &quot;v7&quot;: round(456.456, 2),
1094 &quot;v8&quot;: round(456.456, -1),
1095 &quot;v9&quot;: round(-456.456, -2)
1096};
1097</pre></div></div>
1098</li>
1099<li>
1100
1101<p>The expected result is:</p>
1102
1103<div>
1104<div>
1105<pre class="source">{ &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;: 123460, &quot;v7&quot;: 456.46, &quot;v8&quot;: 460, &quot;v9&quot;: -500 }
1106</pre></div></div>
1107</li>
1108</ul></div>
1109<div class="section">
1110<h3><a name="sign"></a>sign</h3>
1111<ul>
1112
1113<li>
1114
1115<p>Syntax:</p>
1116
1117<div>
1118<div>
1119<pre class="source">sign(numeric_value)
1120</pre></div></div>
1121</li>
1122<li>
1123
1124<p>Computes the sign of the argument.</p>
1125</li>
1126<li>Arguments:
1127<ul>
1128
1129<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>
1130</ul>
1131</li>
1132<li>Return Value:
1133<ul>
1134
1135<li>the sign (a <tt>tinyint</tt>) of the argument, -1 for negative values, 0 for 0, and 1 for positive values,</li>
1136<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
1137<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
1138<li>any other non-numeric input value will cause a type error.</li>
1139</ul>
1140</li>
1141<li>
1142
1143<p>Example:</p>
1144
1145<div>
1146<div>
1147<pre class="source">{ &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;)) };
1148</pre></div></div>
1149</li>
1150<li>
1151
1152<p>The expected result is:</p>
1153
1154<div>
1155<div>
1156<pre class="source">{ &quot;v1&quot;: 1, &quot;v2&quot;: 1, &quot;v3&quot;: 0, &quot;v4&quot;: 1, &quot;v5&quot;: -1 }
1157</pre></div></div>
1158</li>
1159</ul></div>
1160<div class="section">
1161<h3><a name="sin"></a>sin</h3>
1162<ul>
1163
1164<li>
1165
1166<p>Syntax:</p>
1167
1168<div>
1169<div>
1170<pre class="source">sin(numeric_value)
1171</pre></div></div>
1172</li>
1173<li>
1174
1175<p>Computes the sine value of the argument.</p>
1176</li>
1177<li>Arguments:
1178<ul>
1179
1180<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>
1181</ul>
1182</li>
1183<li>Return Value:
1184<ul>
1185
1186<li>the <tt>double</tt> sine value for the argument,</li>
1187<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
1188<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
1189<li>any other non-numeric input value will cause a type error.</li>
1190</ul>
1191</li>
1192<li>
1193
1194<p>Example:</p>
1195
1196<div>
1197<div>
1198<pre class="source">{ &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;)) };
1199</pre></div></div>
1200</li>
1201<li>
1202
1203<p>The expected result is:</p>
1204
1205<div>
1206<div>
1207<pre class="source">{ &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 }
1208</pre></div></div>
1209</li>
1210</ul></div>
1211<div class="section">
1212<h3><a name="sinh"></a>sinh</h3>
1213<ul>
1214
1215<li>
1216
1217<p>Syntax:</p>
1218
1219<div>
1220<div>
1221<pre class="source">sinh(numeric_value)
1222</pre></div></div>
1223</li>
1224<li>
1225
1226<p>Computes the hyperbolic sine value of the argument.</p>
1227</li>
1228<li>Arguments:
1229<ul>
1230
1231<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>
1232</ul>
1233</li>
1234<li>Return Value:
1235<ul>
1236
1237<li>the <tt>double</tt> hyperbolic sine value for the argument,</li>
1238<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
1239<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
1240<li>any other non-numeric input value will cause a type error.</li>
1241</ul>
1242</li>
1243<li>
1244
1245<p>Example:</p>
1246
1247<div>
1248<div>
1249<pre class="source">{ &quot;v1&quot;: sinh(1), &quot;v2&quot;: sinh(2), &quot;v3&quot;: sinh(0), &quot;v4&quot;: sinh(float(&quot;0.5&quot;)), &quot;v5&quot;: sinh(double(&quot;8&quot;)) };
1250</pre></div></div>
1251</li>
1252<li>
1253
1254<p>The expected result is:</p>
1255
1256<div>
1257<div>
1258<pre class="source">{ &quot;v1&quot;: 1.1752011936438014, &quot;v2&quot;: 3.626860407847019, &quot;v3&quot;: 0.0, &quot;v4&quot;: 0.5210953054937474, &quot;v5&quot;: 1490.4788257895502 }
1259</pre></div></div>
1260</li>
1261</ul></div>
1262<div class="section">
1263<h3><a name="sqrt"></a>sqrt</h3>
1264<ul>
1265
1266<li>
1267
1268<p>Syntax:</p>
1269
1270<div>
1271<div>
1272<pre class="source">sqrt(numeric_value)
1273</pre></div></div>
1274</li>
1275<li>
1276
1277<p>Computes the square root of the argument.</p>
1278</li>
1279<li>Arguments:
1280<ul>
1281
1282<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>
1283</ul>
1284</li>
1285<li>Return Value:
1286<ul>
1287
1288<li>the <tt>double</tt> square root value for the argument,</li>
1289<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
1290<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
1291<li>any other non-numeric input value will cause a type error.</li>
1292</ul>
1293</li>
1294<li>
1295
1296<p>Example:</p>
1297
1298<div>
1299<div>
1300<pre class="source">{ &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;)) };
1301</pre></div></div>
1302</li>
1303<li>
1304
1305<p>The expected result is:</p>
1306
1307<div>
1308<div>
1309<pre class="source">{ &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 }
1310</pre></div></div>
1311</li>
1312</ul></div>
1313<div class="section">
1314<h3><a name="tan"></a>tan</h3>
1315<ul>
1316
1317<li>
1318
1319<p>Syntax:</p>
1320
1321<div>
1322<div>
1323<pre class="source">tan(numeric_value)
1324</pre></div></div>
1325</li>
1326<li>
1327
1328<p>Computes the tangent value of the argument.</p>
1329</li>
1330<li>Arguments:
1331<ul>
1332
1333<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>
1334</ul>
1335</li>
1336<li>Return Value:
1337<ul>
1338
1339<li>the <tt>double</tt> tangent value for the argument,</li>
1340<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
1341<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
1342<li>any other non-numeric input value will cause a type error.</li>
1343</ul>
1344</li>
1345<li>
1346
1347<p>Example:</p>
1348
1349<div>
1350<div>
1351<pre class="source">{ &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;)) };
1352</pre></div></div>
1353</li>
1354<li>
1355
1356<p>The expected result is:</p>
1357
1358<div>
1359<div>
1360<pre class="source">{ &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 }
1361</pre></div></div>
1362</li>
1363</ul></div>
1364<div class="section">
1365<h3><a name="tanh"></a>tanh</h3>
1366<ul>
1367
1368<li>
1369
1370<p>Syntax:</p>
1371
1372<div>
1373<div>
1374<pre class="source">tanh(numeric_value)
1375</pre></div></div>
1376</li>
1377<li>
1378
1379<p>Computes the hyperbolic tangent value of the argument.</p>
1380</li>
1381<li>Arguments:
1382<ul>
1383
1384<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>
1385</ul>
1386</li>
1387<li>Return Value:
1388<ul>
1389
1390<li>the <tt>double</tt> hyperbolic tangent value for the argument,</li>
1391<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
1392<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
1393<li>any other non-numeric input value will cause a type error.</li>
1394</ul>
1395</li>
1396<li>
1397
1398<p>Example:</p>
1399
1400<div>
1401<div>
1402<pre class="source">{ &quot;v1&quot;: tanh(1), &quot;v2&quot;: tanh(2), &quot;v3&quot;: tanh(0), &quot;v4&quot;: tanh(float(&quot;0.5&quot;)), &quot;v5&quot;: tanh(double(&quot;8&quot;)) };
1403</pre></div></div>
1404</li>
1405<li>
1406
1407<p>The expected result is:</p>
1408
1409<div>
1410<div>
1411<pre class="source">{ &quot;v1&quot;: 0.7615941559557649, &quot;v2&quot;: 0.964027580075817, &quot;v3&quot;: 0.0, &quot;v4&quot;: 0.4621171572600098, &quot;v5&quot;: 0.999999774929676 }
1412</pre></div></div>
1413</li>
1414</ul></div>
1415<div class="section">
1416<h3><a name="trunc"></a>trunc</h3>
1417<ul>
1418
1419<li>
1420
1421<p>Syntax:</p>
1422
1423<div>
1424<div>
1425<pre class="source">trunc(numeric_value, number_digits)
1426</pre></div></div>
1427</li>
1428<li>
1429
1430<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>
1431</li>
1432<li>Arguments:
1433<ul>
1434
1435<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>
1436<li><tt>number_digits</tt>: a <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt> value.</li>
1437</ul>
1438</li>
1439<li>Return Value:
1440<ul>
1441
1442<li>the <tt>double</tt> tangent value for the argument,</li>
1443<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
1444<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is <tt>missing</tt>,</li>
1445<li>a type error will be raised if:
1446<ul>
1447
1448<li>the first argument is any other non-numeric value,</li>
1449<li>the second argument is any other non-tinyint, non-smallint, non-integer, and non-bigint value.</li>
1450</ul>
1451</li>
1452</ul>
1453</li>
1454<li>
1455
1456<p>Example:</p>
1457
1458<div>
1459<div>
1460<pre class="source">{ &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) };
1461</pre></div></div>
1462</li>
1463<li>
1464
1465<p>The expected result is:</p>
1466
1467<div>
1468<div>
1469<pre class="source">{ &quot;v1&quot;: 1, &quot;v2&quot;: 2, &quot;v3&quot;: 0.12, &quot;v4&quot;: 10.0, &quot;v5&quot;: 1000.525 }
1470</pre></div></div>
1471</li>
1472</ul><!--
1473 ! Licensed to the Apache Software Foundation (ASF) under one
1474 ! or more contributor license agreements. See the NOTICE file
1475 ! distributed with this work for additional information
1476 ! regarding copyright ownership. The ASF licenses this file
1477 ! to you under the Apache License, Version 2.0 (the
1478 ! "License"); you may not use this file except in compliance
1479 ! with the License. You may obtain a copy of the License at
1480 !
1481 ! http://www.apache.org/licenses/LICENSE-2.0
1482 !
1483 ! Unless required by applicable law or agreed to in writing,
1484 ! software distributed under the License is distributed on an
1485 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
1486 ! KIND, either express or implied. See the License for the
1487 ! specific language governing permissions and limitations
1488 ! under the License.
1489 !-->
1490</div>
1491<div class="section">
1492<h3><a name="round_half_to_even"></a>round_half_to_even</h3>
1493<ul>
1494
1495<li>
1496
1497<p>Syntax:</p>
1498
1499<div>
1500<div>
1501<pre class="source">round_half_to_even(numeric_value, [precision])
1502</pre></div></div>
1503</li>
1504<li>
1505
1506<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>
1507</li>
1508<li>Arguments:
1509<ul>
1510
1511<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>
1512<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>
1513</ul>
1514</li>
1515<li>Return Value:
1516<ul>
1517
1518<li>The rounded value for the given number in the same type as the input argument,</li>
1519<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
1520<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
1521<li>a type error will be raised if:
1522<ul>
1523
1524<li>the first argument is any other non-numeric value,</li>
1525<li>or, the second argument is any other non-tinyint, non-smallint, non-integer, or non-bigint value.</li>
1526</ul>
1527</li>
1528</ul>
1529</li>
1530<li>
1531
1532<p>Example:</p>
1533
1534<div>
1535<div>
1536<pre class="source">{
1537 &quot;v1&quot;: round_half_to_even(2013),
1538 &quot;v2&quot;: round_half_to_even(-4036),
1539 &quot;v3&quot;: round_half_to_even(0.8),
1540 &quot;v4&quot;: round_half_to_even(float(&quot;-2013.256&quot;)),
1541 &quot;v5&quot;: round_half_to_even(double(&quot;-2013.893823748327284&quot;)),
1542 &quot;v6&quot;: round_half_to_even(double(&quot;-2013.893823748327284&quot;), 2),
1543 &quot;v7&quot;: round_half_to_even(2013, 4),
1544 &quot;v8&quot;: round_half_to_even(float(&quot;-2013.256&quot;), 5)
1545};
1546</pre></div></div>
1547</li>
1548<li>
1549
1550<p>The expected result is:</p>
1551
1552<div>
1553<div>
1554<pre class="source">{ &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 }
1555</pre></div></div>
1556</li>
1557</ul><!--
1558 ! Licensed to the Apache Software Foundation (ASF) under one
1559 ! or more contributor license agreements. See the NOTICE file
1560 ! distributed with this work for additional information
1561 ! regarding copyright ownership. The ASF licenses this file
1562 ! to you under the Apache License, Version 2.0 (the
1563 ! "License"); you may not use this file except in compliance
1564 ! with the License. You may obtain a copy of the License at
1565 !
1566 ! http://www.apache.org/licenses/LICENSE-2.0
1567 !
1568 ! Unless required by applicable law or agreed to in writing,
1569 ! software distributed under the License is distributed on an
1570 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
1571 ! KIND, either express or implied. See the License for the
1572 ! specific language governing permissions and limitations
1573 ! under the License.
1574 !-->
1575</div></div>
1576<div class="section">
1577<h2><a name="String_Functions"></a><a name="StringFunctions" id="StringFunctions">String Functions</a></h2>
1578<div class="section">
1579<h3><a name="concat"></a>concat</h3>
1580<ul>
1581
1582<li>
1583
1584<p>Syntax:</p>
1585
1586<div>
1587<div>
1588<pre class="source">concat(string1, string2, ...)
1589</pre></div></div>
1590</li>
1591<li>
1592
1593<p>Returns a concatenated string from arguments.</p>
1594</li>
1595<li>Arguments:
1596<ul>
1597
1598<li><tt>string1</tt>: a string value,</li>
1599<li><tt>string2</tt>: a string value,</li>
1600<li>&#x2026;.</li>
1601</ul>
1602</li>
1603<li>Return Value:
1604<ul>
1605
1606<li>a concatenated string from arguments,</li>
1607<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
1608<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
1609<li>any other non-string input value will cause a type error.</li>
1610</ul>
1611</li>
1612<li>
1613
1614<p>Example:</p>
1615
1616<div>
1617<div>
1618<pre class="source">concat(&quot;test &quot;, &quot;driven &quot;, &quot;development&quot;);
1619</pre></div></div>
1620</li>
1621<li>
1622
1623<p>The expected result is:</p>
1624
1625<div>
1626<div>
1627<pre class="source">&quot;test driven development&quot;
1628</pre></div></div>
1629</li>
1630</ul></div>
1631<div class="section">
1632<h3><a name="contains"></a>contains</h3>
1633<ul>
1634
1635<li>
1636
1637<p>Syntax:</p>
1638
1639<div>
1640<div>
1641<pre class="source">contains(string, substring_to_contain)
1642</pre></div></div>
1643</li>
1644<li>
1645
1646<p>Checks whether the string <tt>string</tt> contains the string <tt>substring_to_contain</tt></p>
1647</li>
1648<li>Arguments:
1649<ul>
1650
1651<li><tt>string</tt> : a <tt>string</tt> that might contain the given substring,</li>
1652<li><tt>substring_to_contain</tt> : a target <tt>string</tt> that might be contained.</li>
1653</ul>
1654</li>
1655<li>Return Value:
1656<ul>
1657
1658<li>a <tt>boolean</tt> value, <tt>true</tt> if <tt>string</tt> contains <tt>substring_to_contain</tt>,</li>
1659<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
1660<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
1661<li>any other non-string input value will cause a type error,</li>
1662<li><tt>false</tt> otherwise.</li>
1663</ul>
1664</li>
1665<li>
1666
1667<p>Note: an <a href="similarity.html#UsingIndexesToSupportSimilarityQueries">n_gram index</a> can be utilized for this function.</p>
1668</li>
1669<li>Example:
1670
1671<div>
1672<div>
1673<pre class="source">{ &quot;v1&quot;: contains(&quot;I like x-phone&quot;, &quot;phone&quot;), &quot;v2&quot;: contains(&quot;one&quot;, &quot;phone&quot;) };
1674</pre></div></div>
1675</li>
1676<li>
1677
1678<p>The expected result is:</p>
1679
1680<div>
1681<div>
1682<pre class="source">{ &quot;v1&quot;: true, &quot;v2&quot;: false }
1683</pre></div></div>
1684</li>
1685</ul></div>
1686<div class="section">
1687<h3><a name="ends_with"></a>ends_with</h3>
1688<ul>
1689
1690<li>
1691
1692<p>Syntax:</p>
1693
1694<div>
1695<div>
1696<pre class="source">ends_with(string, substring_to_end_with)
1697</pre></div></div>
1698</li>
1699<li>
1700
1701<p>Checks whether the string <tt>string</tt> ends with the string <tt>substring_to_end_with</tt>.</p>
1702</li>
1703<li>Arguments:
1704<ul>
1705
1706<li><tt>string</tt> : a <tt>string</tt> that might end with the given string,</li>
1707<li><tt>substring_to_end_with</tt> : a <tt>string</tt> that might be contained as the ending substring.</li>
1708</ul>
1709</li>
1710<li>Return Value:
1711<ul>
1712
1713<li>a <tt>boolean</tt> value, <tt>true</tt> if <tt>string</tt> contains <tt>substring_to_contain</tt>,</li>
1714<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
1715<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
1716<li>any other non-string input value will cause a type error,</li>
1717<li><tt>false</tt> otherwise.</li>
1718</ul>
1719</li>
1720<li>
1721
1722<p>Example:</p>
1723
1724<div>
1725<div>
1726<pre class="source">{
1727 &quot;v1&quot;: ends_with(&quot; love product-b its shortcut_menu is awesome:)&quot;, &quot;:)&quot;),
1728 &quot;v2&quot;: ends_with(&quot; awsome:)&quot;, &quot;:-)&quot;)
1729};
1730</pre></div></div>
1731</li>
1732<li>
1733
1734<p>The expected result is:</p>
1735
1736<div>
1737<div>
1738<pre class="source">{ &quot;v1&quot;: true, &quot;v2&quot;: false }
1739</pre></div></div>
1740</li>
1741</ul></div>
1742<div class="section">
1743<h3><a name="initcap_.28or_title.29"></a>initcap (or title)</h3>
1744<ul>
1745
1746<li>
1747
1748<p>Syntax:</p>
1749
1750<div>
1751<div>
1752<pre class="source">initcap(string)
1753</pre></div></div>
1754</li>
1755<li>
1756
1757<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>
1758</li>
1759<li>Arguments:
1760<ul>
1761
1762<li><tt>string</tt> : a <tt>string</tt> to be converted.</li>
1763</ul>
1764</li>
1765<li>Return Value:
1766<ul>
1767
1768<li>a <tt>string</tt> as the title form of the given <tt>string</tt>,</li>
1769<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
1770<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
1771<li>any other non-string input value will cause a type error.</li>
1772</ul>
1773</li>
1774<li>
1775
1776<p>Example:</p>
1777
1778<div>
1779<div>
1780<pre class="source">{ &quot;v1&quot;: initcap(&quot;ASTERIXDB is here!&quot;), &quot;v2&quot;: title(&quot;ASTERIXDB is here!&quot;) };
1781</pre></div></div>
1782</li>
1783<li>
1784
1785<p>The expected result is:</p>
1786
1787<div>
1788<div>
1789<pre class="source">{ &quot;v1&quot;: &quot;Asterixdb Is Here!&quot;, &quot;v2&quot;: &quot;Asterixdb Is Here!&quot; }
1790</pre></div></div>
1791</li>
1792</ul></div>
1793<div class="section">
1794<h3><a name="length"></a>length</h3>
1795<ul>
1796
1797<li>
1798
1799<p>Syntax:</p>
1800
1801<div>
1802<div>
1803<pre class="source">length(string)
1804</pre></div></div>
1805</li>
1806<li>
1807
1808<p>Returns the length of the string <tt>string</tt>. Note that the length is in the unit of code point. See the following examples for more details.</p>
1809</li>
1810<li>Arguments:
1811<ul>
1812
1813<li><tt>string</tt> : a <tt>string</tt> or <tt>null</tt> that represents the string to be checked.</li>
1814</ul>
1815</li>
1816<li>Return Value:
1817<ul>
1818
1819<li>an <tt>bigint</tt> that represents the length of <tt>string</tt>,</li>
1820<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
1821<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
1822<li>any other non-string input value will cause a type error.</li>
1823</ul>
1824</li>
1825<li>
1826
1827<p>Example:</p>
1828
1829<div>
1830<div>
1831<pre class="source">length(&quot;test string&quot;);
1832</pre></div></div>
1833</li>
1834<li>
1835
1836<p>The expected result is:</p>
1837
1838<div>
1839<div>
1840<pre class="source">11
1841</pre></div></div>
1842</li>
1843<li>
1844
1845<p>Example:</p>
1846
1847<div>
1848<div>
1849<pre class="source">length(&quot;&#x1f469;&#x200d;&#x1f469;&#x200d;&#x1f467;&#x200d;&#x1f466;&quot;);
1850</pre></div></div>
1851</li>
1852<li>
1853
1854<p>The expected result is (the emoji character &#x1f469;&#x200d;&#x1f469;&#x200d;&#x1f467;&#x200d;&#x1f466; has 7 code points):</p>
1855
1856<div>
1857<div>
1858<pre class="source">7
1859</pre></div></div>
1860</li>
1861</ul></div>
1862<div class="section">
1863<h3><a name="lower"></a>lower</h3>
1864<ul>
1865
1866<li>
1867
1868<p>Syntax:</p>
1869
1870<div>
1871<div>
1872<pre class="source">lower(string)
1873</pre></div></div>
1874</li>
1875<li>
1876
1877<p>Converts a given string <tt>string</tt> to its lowercase form.</p>
1878</li>
1879<li>Arguments:
1880<ul>
1881
1882<li><tt>string</tt> : a <tt>string</tt> to be converted.</li>
1883</ul>
1884</li>
1885<li>Return Value:
1886<ul>
1887
1888<li>a <tt>string</tt> as the lowercase form of the given <tt>string</tt>,</li>
1889<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
1890<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
1891<li>any other non-string input value will cause a type error.</li>
1892</ul>
1893</li>
1894<li>
1895
1896<p>Example:</p>
1897
1898<div>
1899<div>
1900<pre class="source">lower(&quot;ASTERIXDB&quot;);
1901</pre></div></div>
1902</li>
1903<li>
1904
1905<p>The expected result is:</p>
1906
1907<div>
1908<div>
1909<pre class="source">&quot;asterixdb&quot;
1910</pre></div></div>
1911</li>
1912</ul></div>
1913<div class="section">
1914<h3><a name="ltrim"></a>ltrim</h3>
1915<ul>
1916
1917<li>
1918
1919<p>Syntax:</p>
1920
1921<div>
1922<div>
1923<pre class="source">ltrim(string[, chars]);
1924</pre></div></div>
1925</li>
1926<li>
1927
1928<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. Note that here one character means one code point. For example, the emoji 4-people-family notation &#x201c;&#x1f469;&#x200d;&#x1f469;&#x200d;&#x1f467;&#x200d;&#x1f466;&#x201d; contains 7 code points, and it is possible to trim a few code points (such as a 2-people-family &#x201c;&#x1f468;&#x200d;&#x1f466;&#x201d;) from it. See the following example for more details.</p>
1929</li>
1930<li>Arguments:
1931<ul>
1932
1933<li><tt>string</tt> : a <tt>string</tt> to be trimmed,</li>
1934<li><tt>chars</tt> : a <tt>string</tt> that contains characters that are used to trim.</li>
1935</ul>
1936</li>
1937<li>Return Value:
1938<ul>
1939
1940<li>a trimmed, new <tt>string</tt>,</li>
1941<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
1942<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
1943<li>any other non-string input value will cause a type error.</li>
1944</ul>
1945</li>
1946<li>Related functions: see <tt>trim()</tt>, <tt>rtrim()</tt></li>
1947<li>
1948
1949<p>Example:</p>
1950
1951<div>
1952<div>
1953<pre class="source">ltrim(&quot;me like x-phone&quot;, &quot;eml&quot;);
1954</pre></div></div>
1955</li>
1956<li>
1957
1958<p>The expected result is:</p>
1959
1960<div>
1961<div>
1962<pre class="source">&quot; like x-phone&quot;
1963</pre></div></div>
1964</li>
1965<li>
1966
1967<p>Example with multi-codepoint notation (trim the man and boy from the family of man, woman, girl and boy):</p>
1968
1969<div>
1970<div>
1971<pre class="source">ltrim(&quot;&#x1f468;&#x200d;&#x1f469;&#x200d;&#x1f467;&#x200d;&#x1f466;&quot;, &quot;&#x1f468;&#x200d;&#x1f466;&quot;)
1972</pre></div></div>
1973</li>
1974<li>
1975
1976<p>The expected result is (only woman, girl and boy are left in the family):</p>
1977
1978<div>
1979<div>
1980<pre class="source">&quot;&#x1f469;&#x200d;&#x1f467;&#x200d;&#x1f466;&quot;
1981</pre></div></div>
1982</li>
1983</ul></div>
1984<div class="section">
1985<h3><a name="position"></a>position</h3>
1986<ul>
1987
1988<li>
1989
1990<p>Syntax:</p>
1991
1992<div>
1993<div>
1994<pre class="source">position(string, string_pattern)
1995</pre></div></div>
1996</li>
1997<li>
1998
1999<p>Returns the first position of <tt>string_pattern</tt> within <tt>string</tt>. The result is counted in the unit of code points. See the following example for more details.</p>
2000</li>
2001<li>
2002
2003<p>The function returns the 0-based position. Another version of the function returns the 1-based position. Below are the aliases for each version:</p>
2004<ul>
2005
2006<li>0-based: <tt>position</tt>, <tt>pos</tt>, <tt>position0</tt>, <tt>pos0</tt>.</li>
2007<li>1-based: <tt>position1</tt>, <tt>pos1</tt>.</li>
2008</ul>
2009</li>
2010<li>
2011
2012<p>Arguments:</p>
2013<ul>
2014
2015<li><tt>string</tt> : a <tt>string</tt> that might contain the pattern.</li>
2016<li><tt>string_pattern</tt> : a pattern <tt>string</tt> to be matched.</li>
2017</ul>
2018</li>
2019<li>Return Value:
2020<ul>
2021
2022<li>the first position that <tt>string_pattern</tt> appears within <tt>string</tt> (starting at 0), or -1 if it does not appear,</li>
2023<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2024<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2025<li>any other non-string input value will return a <tt>null</tt>.</li>
2026</ul>
2027</li>
2028<li>
2029
2030<p>Example:</p>
2031
2032<div>
2033<div>
2034<pre class="source">{
2035 &quot;v1&quot;: position(&quot;ppphonepp&quot;, &quot;phone&quot;),
2036 &quot;v2&quot;: position(&quot;hone&quot;, &quot;phone&quot;),
2037 &quot;v3&quot;: position1(&quot;ppphonepp&quot;, &quot;phone&quot;),
2038 &quot;v4&quot;: position1(&quot;hone&quot;, &quot;phone&quot;)
2039};
2040</pre></div></div>
2041</li>
2042<li>
2043
2044<p>The expected result is:</p>
2045
2046<div>
2047<div>
2048<pre class="source">{ &quot;v1&quot;: 2, &quot;v2&quot;: -1, v3&quot;: 3, &quot;v4&quot;: -1 }
2049</pre></div></div>
2050</li>
2051<li>
2052
2053<p>Example of multi-code-point character:</p>
2054
2055<div>
2056<div>
2057<pre class="source">position(&quot;&#x1f469;&#x200d;&#x1f469;&#x200d;&#x1f467;&#x200d;&#x1f466;&#x1f3c0;&quot;, &quot;&#x1f3c0;&quot;);
2058</pre></div></div>
2059</li>
2060<li>
2061
2062<p>The expected result is (the emoji family character has 7 code points):</p>
2063
2064<div>
2065<div>
2066<pre class="source">7
2067</pre></div></div>
2068</li>
2069</ul></div>
2070<div class="section">
2071<h3><a name="regexp_contains"></a>regexp_contains</h3>
2072<ul>
2073
2074<li>
2075
2076<p>Syntax:</p>
2077
2078<div>
2079<div>
2080<pre class="source">regexp_contains(string, string_pattern[, string_flags])
2081</pre></div></div>
2082</li>
2083<li>
2084
2085<p>Checks whether the strings <tt>string</tt> contains the regular expression pattern <tt>string_pattern</tt> (a Java regular expression pattern).</p>
2086</li>
2087<li>
2088
2089<p>Aliases:</p>
2090<ul>
2091
2092<li><tt>regexp_contains</tt>, <tt>regex_contains</tt>, <tt>contains_regexp</tt>, <tt>contains_regex</tt>.</li>
2093</ul>
2094</li>
2095<li>
2096
2097<p>Arguments:</p>
2098<ul>
2099
2100<li><tt>string</tt> : a <tt>string</tt> that might contain the pattern.</li>
2101<li><tt>string_pattern</tt> : a pattern <tt>string</tt> to be matched.</li>
2102<li><tt>string_flag</tt> : (Optional) a <tt>string</tt> with flags to be used during regular expression matching.
2103<ul>
2104
2105<li>The following modes are enabled with these flags: dotall (s), multiline (m), case_insensitive (i), and comments and whitespace (x).</li>
2106</ul>
2107</li>
2108</ul>
2109</li>
2110<li>Return Value:
2111<ul>
2112
2113<li>a <tt>boolean</tt>, returns <tt>true</tt> if <tt>string</tt> contains the pattern <tt>string_pattern</tt>, <tt>false</tt> otherwise.</li>
2114<li><tt>missing</tt> if any argument is a <tt>missing</tt> value.</li>
2115<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value.</li>
2116<li>any other non-string input value will return a <tt>null</tt>.</li>
2117</ul>
2118</li>
2119<li>
2120
2121<p>Example:</p>
2122
2123<div>
2124<div>
2125<pre class="source">{
2126 &quot;v1&quot;: regexp_contains(&quot;pphonepp&quot;, &quot;p*hone&quot;),
2127 &quot;v2&quot;: regexp_contains(&quot;hone&quot;, &quot;p+hone&quot;)
2128};
2129</pre></div></div>
2130</li>
2131<li>
2132
2133<p>The expected result is:</p>
2134
2135<div>
2136<div>
2137<pre class="source">{ &quot;v1&quot;: true, &quot;v2&quot;: false }
2138</pre></div></div>
2139</li>
2140</ul></div>
2141<div class="section">
2142<h3><a name="regexp_like"></a>regexp_like</h3>
2143<ul>
2144
2145<li>
2146
2147<p>Syntax:</p>
2148
2149<div>
2150<div>
2151<pre class="source">regexp_like(string, string_pattern[, string_flags])
2152</pre></div></div>
2153</li>
2154<li>
2155
2156<p>Checks whether the string <tt>string</tt> exactly matches the regular expression pattern <tt>string_pattern</tt> (a Java regular expression pattern).</p>
2157</li>
2158<li>
2159
2160<p>Aliases:</p>
2161<ul>
2162
2163<li><tt>regexp_like</tt>, <tt>regex_like</tt>.</li>
2164</ul>
2165</li>
2166<li>
2167
2168<p>Arguments:</p>
2169<ul>
2170
2171<li><tt>string</tt> : a <tt>string</tt> that might contain the pattern.</li>
2172<li><tt>string_pattern</tt> : a pattern <tt>string</tt> that might be contained.</li>
2173<li><tt>string_flag</tt> : (Optional) a <tt>string</tt> with flags to be used during regular expression matching.
2174<ul>
2175
2176<li>The following modes are enabled with these flags: dotall (s), multiline (m), case_insensitive (i), and comments and whitespace (x).</li>
2177</ul>
2178</li>
2179</ul>
2180</li>
2181<li>Return Value:
2182<ul>
2183
2184<li>a <tt>boolean</tt> value, <tt>true</tt> if <tt>string</tt> contains the pattern <tt>string_pattern</tt>, <tt>false</tt> otherwise.</li>
2185<li><tt>missing</tt> if any argument is a <tt>missing</tt> value.</li>
2186<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value.</li>
2187<li>any other non-string input value will return a <tt>null</tt>.</li>
2188</ul>
2189</li>
2190<li>
2191
2192<p>Example:</p>
2193
2194<div>
2195<div>
2196<pre class="source">{
2197 &quot;v1&quot;: regexp_like(&quot; can't stand acast the network is horrible:(&quot;, &quot;.*acast.*&quot;),
2198 &quot;v2&quot;: regexp_like(&quot;acast&quot;, &quot;.*acst.*&quot;)
2199};
2200</pre></div></div>
2201</li>
2202<li>
2203
2204<p>The expected result is:</p>
2205
2206<div>
2207<div>
2208<pre class="source">{ &quot;v1&quot;: true, &quot;v2&quot;: false }
2209</pre></div></div>
2210</li>
2211</ul></div>
2212<div class="section">
2213<h3><a name="regexp_position"></a>regexp_position</h3>
2214<ul>
2215
2216<li>
2217
2218<p>Syntax:</p>
2219
2220<div>
2221<div>
2222<pre class="source">regexp_position(string, string_pattern[, string_flags])
2223</pre></div></div>
2224</li>
2225<li>
2226
2227<p>Returns first position of the regular expression <tt>string_pattern</tt> (a Java regular expression pattern) within <tt>string</tt>. The function returns the 0-based position. Another version of the function returns the 1-based position. Below are the aliases for each version:</p>
2228</li>
2229<li>
2230
2231<p>Aliases:</p>
2232<ul>
2233
2234<li>0-Based: <tt>regexp_position</tt>, <tt>regexp_pos</tt>, <tt>regexp_position0</tt>, <tt>regexp_pos0</tt>, <tt>regex_position</tt>, <tt>regex_pos</tt>, <tt>regex_position0</tt>, <tt>regex_pos0</tt>.</li>
2235<li>1-Based: <tt>regexp_position1</tt>, <tt>regexp_pos1</tt>, <tt>regex_position1</tt> <tt>regex_pos1</tt>.</li>
2236</ul>
2237</li>
2238<li>
2239
2240<p>Arguments:</p>
2241<ul>
2242
2243<li><tt>string</tt> : a <tt>string</tt> that might contain the pattern.</li>
2244<li><tt>string_pattern</tt> : a pattern <tt>string</tt> to be matched.</li>
2245<li><tt>string_flag</tt> : (Optional) a <tt>string</tt> with flags to be used during regular expression matching.
2246<ul>
2247
2248<li>The following modes are enabled with these flags: dotall (s), multiline (m), case_insensitive (i), and comments and whitespace (x).</li>
2249</ul>
2250</li>
2251</ul>
2252</li>
2253<li>Return Value:
2254<ul>
2255
2256<li>the first position that the regular expression <tt>string_pattern</tt> appears in <tt>string</tt> (starting at 0), or -1 if it does not appear.</li>
2257<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2258<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2259<li>any other non-string input value will return a <tt>null</tt>.</li>
2260</ul>
2261</li>
2262<li>
2263
2264<p>Example:</p>
2265
2266<div>
2267<div>
2268<pre class="source">{
2269 &quot;v1&quot;: regexp_position(&quot;pphonepp&quot;, &quot;p*hone&quot;),
2270 &quot;v2&quot;: regexp_position(&quot;hone&quot;, &quot;p+hone&quot;),
2271 &quot;v3&quot;: regexp_position1(&quot;pphonepp&quot;, &quot;p*hone&quot;),
2272 &quot;v4&quot;: regexp_position1(&quot;hone&quot;, &quot;p+hone&quot;)
2273};
2274</pre></div></div>
2275</li>
2276<li>
2277
2278<p>The expected result is:</p>
2279
2280<div>
2281<div>
2282<pre class="source">{ &quot;v1&quot;: 0, &quot;v2&quot;: -1, &quot;v3&quot;: 1, &quot;v4&quot;: -1 }
2283</pre></div></div>
2284</li>
2285</ul></div>
2286<div class="section">
2287<h3><a name="regexp_replace"></a>regexp_replace</h3>
2288<ul>
2289
2290<li>
2291
2292<p>Syntax:</p>
2293
2294<div>
2295<div>
2296<pre class="source">regexp_replace(string, string_pattern, string_replacement[, string_flags])
2297regexp_replace(string, string_pattern, string_replacement[, replacement_limit])
2298</pre></div></div>
2299</li>
2300<li>
2301
2302<p>Checks whether the string <tt>string</tt> matches the given regular expression pattern <tt>string_pattern</tt> (a Java regular expression pattern), and replaces the matched pattern <tt>string_pattern</tt> with the new pattern <tt>string_replacement</tt>.</p>
2303</li>
2304<li>
2305
2306<p>Aliases:</p>
2307<ul>
2308
2309<li><tt>regexp_replace</tt>, <tt>regex_replace</tt>.</li>
2310</ul>
2311</li>
2312<li>
2313
2314<p>Arguments:</p>
2315<ul>
2316
2317<li><tt>string</tt> : a <tt>string</tt> that might contain the pattern.</li>
2318<li><tt>string_pattern</tt> : a pattern <tt>string</tt> to be matched.</li>
2319<li><tt>string_replacement</tt> : a pattern <tt>string</tt> to be used as the replacement.</li>
2320<li><tt>string_flag</tt> : (Optional) a <tt>string</tt> with flags to be used during replace.
2321<ul>
2322
2323<li>The following modes are enabled with these flags: dotall (s), multiline (m), case_insensitive (i), and comments and whitespace (x).</li>
2324</ul>
2325</li>
2326<li><tt>replacement_limit</tt>: (Optional) an <tt>integer</tt> specifying the maximum number of replacements to make (if negative then all occurrences will be replaced)</li>
2327</ul>
2328</li>
2329<li>Return Value:
2330<ul>
2331
2332<li>Returns a <tt>string</tt> that is obtained after the replacements.</li>
2333<li><tt>missing</tt> if any argument is a <tt>missing</tt> value.</li>
2334<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value.</li>
2335<li>any other non-string input value will return a <tt>null</tt>.</li>
2336</ul>
2337</li>
2338<li>
2339
2340<p>Example:</p>
2341
2342<div>
2343<div>
2344<pre class="source">regexp_replace(&quot; like x-phone the voicemail_service is awesome&quot;, &quot; like x-phone&quot;, &quot;like product-a&quot;);
2345</pre></div></div>
2346</li>
2347<li>
2348
2349<p>The expected result is:</p>
2350
2351<div>
2352<div>
2353<pre class="source">&quot;like product-a the voicemail_service is awesome&quot;
2354</pre></div></div>
2355</li>
2356</ul></div>
2357<div class="section">
2358<h3><a name="repeat"></a>repeat</h3>
2359<ul>
2360
2361<li>
2362
2363<p>Syntax:</p>
2364
2365<div>
2366<div>
2367<pre class="source">repeat(string, n)
2368</pre></div></div>
2369</li>
2370<li>
2371
2372<p>Returns a string formed by repeating the input <tt>string</tt> <tt>n</tt> times.</p>
2373</li>
2374<li>Arguments:
2375<ul>
2376
2377<li><tt>string</tt> : a <tt>string</tt> to be repeated,</li>
2378<li><tt>n</tt> : an <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt> value - how many times the string should be repeated.</li>
2379</ul>
2380</li>
2381<li>Return Value:
2382<ul>
2383
2384<li>a string that repeats the input <tt>string</tt> <tt>n</tt> times,</li>
2385<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2386<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2387<li>a type error will be raised if:
2388<ul>
2389
2390<li>the first argument is any other non-string value,</li>
2391<li>or, the second argument is not a <tt>tinyint</tt>, <tt>smallint</tt>, <tt>integer</tt>, or <tt>bigint</tt>.</li>
2392</ul>
2393</li>
2394</ul>
2395</li>
2396<li>
2397
2398<p>Example:</p>
2399
2400<div>
2401<div>
2402<pre class="source">repeat(&quot;test&quot;, 3);
2403</pre></div></div>
2404</li>
2405<li>
2406
2407<p>The expected result is:</p>
2408
2409<div>
2410<div>
2411<pre class="source">&quot;testtesttest&quot;
2412</pre></div></div>
2413</li>
2414</ul></div>
2415<div class="section">
2416<h3><a name="replace"></a>replace</h3>
2417<ul>
2418
2419<li>
2420
2421<p>Syntax:</p>
2422
2423<div>
2424<div>
2425<pre class="source">replace(string, search_string, replacement_string[, limit])
2426</pre></div></div>
2427</li>
2428<li>
2429
2430<p>Finds occurrences of the given substring <tt>search_string</tt> in the input string <tt>string</tt> and replaces them with the new substring <tt>replacement_string</tt>.</p>
2431</li>
2432<li>Arguments:
2433<ul>
2434
2435<li><tt>string</tt> : an input <tt>string</tt>,</li>
2436<li><tt>search_string</tt> : a <tt>string</tt> substring to be searched for,</li>
2437<li><tt>replacement_string</tt> : a <tt>string</tt> to be used as the replacement,</li>
2438<li><tt>limit</tt> : (Optional) an <tt>integer</tt> - maximum number of occurrences to be replaced. If not specified or negative then all occurrences will be replaced</li>
2439</ul>
2440</li>
2441<li>Return Value:
2442<ul>
2443
2444<li>Returns a <tt>string</tt> that is obtained after the replacements,</li>
2445<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2446<li>any other non-string input value or non-integer <tt>limit</tt> will cause a type error,</li>
2447<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value.</li>
2448</ul>
2449</li>
2450<li>
2451
2452<p>Example:</p>
2453
2454<div>
2455<div>
2456<pre class="source">{
2457 &quot;v1&quot;: replace(&quot; like x-phone the voicemail_service is awesome&quot;, &quot; like x-phone&quot;, &quot;like product-a&quot;),
2458 &quot;v2&quot;: replace(&quot;x-phone and x-phone&quot;, &quot;x-phone&quot;, &quot;product-a&quot;, 1)
2459};
2460</pre></div></div>
2461</li>
2462<li>
2463
2464<p>The expected result is:</p>
2465
2466<div>
2467<div>
2468<pre class="source">{
2469 &quot;v1&quot;: &quot;like product-a the voicemail_service is awesome&quot;,
2470 &quot;v2&quot;: &quot;product-a and x-phone&quot;
2471}
2472</pre></div></div>
2473</li>
2474</ul></div>
2475<div class="section">
2476<h3><a name="reverse"></a>reverse</h3>
2477<ul>
2478
2479<li>
2480
2481<p>Syntax:</p>
2482
2483<div>
2484<div>
2485<pre class="source">reverse(string)
2486</pre></div></div>
2487</li>
2488<li>
2489
2490<p>Returns a string formed by reversing characters in the input <tt>string</tt>. For characters of multiple code points, code point is the minimal unit to reverse. See the following examples for more details.</p>
2491</li>
2492<li>Arguments:
2493<ul>
2494
2495<li><tt>string</tt> : a <tt>string</tt> to be reversed</li>
2496</ul>
2497</li>
2498<li>Return Value:
2499<ul>
2500
2501<li>a string containing characters from the the input <tt>string</tt> in the reverse order,</li>
2502<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2503<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2504<li>a type error will be raised if:
2505<ul>
2506
2507<li>the first argument is any other non-string value</li>
2508</ul>
2509</li>
2510</ul>
2511</li>
2512<li>
2513
2514<p>Example:</p>
2515
2516<div>
2517<div>
2518<pre class="source">reverse(&quot;hello&quot;);
2519</pre></div></div>
2520</li>
2521<li>
2522
2523<p>The expected result is:</p>
2524
2525<div>
2526<div>
2527<pre class="source">&quot;olleh&quot;
2528</pre></div></div>
2529</li>
2530<li>
2531
2532<p>Example of multi-code-point character (Korean):</p>
2533
2534<div>
2535<div>
2536<pre class="source">reverse(&quot;&#x1112;&#x1161;&#x11ab;&#x1100;&#x1173;&#x11af;&quot;);
2537</pre></div></div>
2538</li>
2539<li>
2540
2541<p>The expected result is (the Korean characters are splitted into code points and then the code points are reversed):</p>
2542
2543<div>
2544<div>
2545<pre class="source">&quot;&#x11af;&#x1173;&#x1100;&#x11ab;&#x1161;&#x1112;&quot;
2546</pre></div></div>
2547</li>
2548</ul></div>
2549<div class="section">
2550<h3><a name="rtrim"></a>rtrim</h3>
2551<ul>
2552
2553<li>
2554
2555<p>Syntax:</p>
2556
2557<div>
2558<div>
2559<pre class="source">rtrim(string[, chars]);
2560</pre></div></div>
2561</li>
2562<li>
2563
2564<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. Note that here one character means one code point. For example, the emoji 4-people-family notation &#x201c;&#x1f469;&#x200d;&#x1f469;&#x200d;&#x1f467;&#x200d;&#x1f466;&#x201d; contains 7 code points, and it is possible to trim a few code points (such as a 2-people-family &#x201c;&#x1f468;&#x200d;&#x1f466;&#x201d;) from it. See the following example for more details.</p>
2565</li>
2566<li>Arguments:
2567<ul>
2568
2569<li><tt>string</tt> : a <tt>string</tt> to be trimmed,</li>
2570<li><tt>chars</tt> : a <tt>string</tt> that contains characters that are used to trim.</li>
2571</ul>
2572</li>
2573<li>Return Value:
2574<ul>
2575
2576<li>a trimmed, new <tt>string</tt>,</li>
2577<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2578<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2579<li>any other non-string input value will cause a type error.</li>
2580</ul>
2581</li>
2582<li>Related functions: see <tt>trim()</tt>, <tt>ltrim()</tt></li>
2583<li>
2584
2585<p>Example:</p>
2586
2587<div>
2588<div>
2589<pre class="source">{
2590 &quot;v1&quot;: rtrim(&quot;i like x-phone&quot;, &quot;x-phone&quot;),
2591 &quot;v2&quot;: rtrim(&quot;i like x-phone&quot;, &quot;onexph&quot;)
2592};
2593</pre></div></div>
2594</li>
2595<li>
2596
2597<p>The expected result is:</p>
2598
2599<div>
2600<div>
2601<pre class="source">{ &quot;v1&quot;: &quot;i like &quot;, &quot;v2&quot;: &quot;i like x-&quot; }
2602</pre></div></div>
2603</li>
2604<li>
2605
2606<p>Example with multi-codepoint notation (trim the man and boy from the family of man, woman, girl and boy):</p>
2607
2608<div>
2609<div>
2610<pre class="source">rtrim(&quot;&#x1f468;&#x200d;&#x1f469;&#x200d;&#x1f467;&#x200d;&#x1f466;&quot;, &quot;&#x1f468;&#x200d;&#x1f466;&quot;)
2611</pre></div></div>
2612</li>
2613<li>
2614
2615<p>The expected result is (only man, woman and girl are left in the family):</p>
2616
2617<div>
2618<div>
2619<pre class="source">&quot;&#x1f468;&#x200d;&#x1f469;&#x200d;&#x1f467;&quot;
2620</pre></div></div>
2621</li>
2622</ul></div>
2623<div class="section">
2624<h3><a name="split"></a>split</h3>
2625<ul>
2626
2627<li>
2628
2629<p>Syntax:</p>
2630
2631<div>
2632<div>
2633<pre class="source">split(string, sep)
2634</pre></div></div>
2635</li>
2636<li>
2637
2638<p>Splits the input <tt>string</tt> into an array of substrings separated by the string <tt>sep</tt>.</p>
2639</li>
2640<li>Arguments:
2641<ul>
2642
2643<li><tt>string</tt> : a <tt>string</tt> to be split.</li>
2644</ul>
2645</li>
2646<li>Return Value:
2647<ul>
2648
2649<li>an array of substrings by splitting the input <tt>string</tt> by <tt>sep</tt>,</li>
2650<li>in case of two consecutive <tt>sep</tt>s in the <tt>string</tt>, the result of splitting the two consecutive <tt>sep</tt>s will be the empty string <tt>&quot;&quot;</tt>,</li>
2651<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
2652<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
2653<li>any other non-string input value will cause a type error.</li>
2654</ul>
2655</li>
2656<li>
2657
2658<p>Example:</p>
2659
2660<div>
2661<div>
2662<pre class="source">split(&quot;test driven development&quot;, &quot; &quot;);
2663</pre></div></div>
2664</li>
2665<li>
2666
2667<p>The expected result is:</p>
2668
2669<div>
2670<div>
2671<pre class="source">[ &quot;test&quot;, &quot;driven&quot;, &quot;development&quot; ]
2672</pre></div></div>
2673</li>
2674<li>
2675
2676<p>Example with two consecutive <tt>sep</tt>s in the <tt>string</tt>:</p>
2677
2678<div>
2679<div>
2680<pre class="source">split(&quot;123//456&quot;, &quot;/&quot;);
2681</pre></div></div>
2682</li>
2683<li>
2684
2685<p>The expected result is:</p>
2686
2687<div>
2688<div>
2689<pre class="source">[ &quot;123&quot;, &quot;&quot;, &quot;456&quot; ]
2690</pre></div></div>
2691</li>
2692</ul></div>
2693<div class="section">
2694<h3><a name="starts_with"></a>starts_with</h3>
2695<ul>
2696
2697<li>
2698
2699<p>Syntax:</p>
2700
2701<div>
2702<div>
2703<pre class="source">starts_with(string, substring_to_start_with)
2704</pre></div></div>
2705</li>
2706<li>
2707
2708<p>Checks whether the string <tt>string</tt> starts with the string <tt>substring_to_start_with</tt>.</p>
2709</li>
2710<li>Arguments:
2711<ul>
2712
2713<li><tt>string</tt> : a <tt>string</tt> that might start with the given string.</li>
2714<li><tt>substring_to_start_with</tt> : a <tt>string</tt> that might be contained as the starting substring.</li>
2715</ul>
2716</li>
2717<li>Return Value:
2718<ul>
2719
2720<li>a <tt>boolean</tt>, returns <tt>true</tt> if <tt>string</tt> starts with the string <tt>substring_to_start_with</tt>,</li>
2721<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2722<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2723<li>any other non-string input value will cause a type error,</li>
2724<li><tt>false</tt> otherwise.</li>
2725</ul>
2726</li>
2727<li>
2728
2729<p>Example:</p>
2730
2731<div>
2732<div>
2733<pre class="source">{
2734 &quot;v1&quot; : starts_with(&quot; like the plan, amazing&quot;, &quot; like&quot;),
2735 &quot;v2&quot; : starts_with(&quot;I like the plan, amazing&quot;, &quot; like&quot;)
2736};
2737</pre></div></div>
2738</li>
2739<li>
2740
2741<p>The expected result is:</p>
2742
2743<div>
2744<div>
2745<pre class="source">{ &quot;v1&quot;: true, &quot;v2&quot;: false }
2746</pre></div></div>
2747</li>
2748</ul></div>
2749<div class="section">
2750<h3><a name="substr"></a>substr</h3>
2751<ul>
2752
2753<li>
2754
2755<p>Syntax:</p>
2756
2757<div>
2758<div>
2759<pre class="source">substr(string, offset[, length])
2760</pre></div></div>
2761</li>
2762<li>
2763
2764<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>. Note that both of the <tt>offset</tt> and <tt>length</tt> are in the unit of code point (e.g. the emoji family &#x1f468;&#x200d;&#x1f469;&#x200d;&#x1f467;&#x200d;&#x1f466; has 7 code points). The function uses the 0-based position. Another version of the function uses the 1-based position. Below are the aliases for each version:</p>
2765</li>
2766<li>
2767
2768<p>Aliases:</p>
2769<ul>
2770
2771<li>0-Based: <tt>substring</tt>, <tt>substr</tt>, <tt>substring0</tt>, <tt>substr0</tt>.</li>
2772<li>1-Based: <tt>substring1</tt>, <tt>substr1</tt>.</li>
2773</ul>
2774</li>
2775<li>
2776
2777<p>Arguments:</p>
2778<ul>
2779
2780<li><tt>string</tt> : a <tt>string</tt> to be extracted.</li>
2781<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> (starting at 0). If negative then counted from the end of the string.</li>
2782<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>
2783</ul>
2784</li>
2785<li>Return Value:
2786<ul>
2787
2788<li>a <tt>string</tt> that represents the substring,</li>
2789<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2790<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value, or if the substring could not be obtained because the starting offset is not within string bounds or <tt>length</tt> is negative.</li>
2791<li>a <tt>null</tt> will be returned if:
2792<ul>
2793
2794<li>the first argument is any other non-string value.</li>
2795<li>the second argument is not a <tt>tinyint</tt>, <tt>smallint</tt>, <tt>integer</tt>, or <tt>bigint</tt>.</li>
2796<li>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>
2797</ul>
2798</li>
2799</ul>
2800</li>
2801<li>
2802
2803<p>Example:</p>
2804
2805<div>
2806<div>
2807<pre class="source">{ &quot;v1&quot;: substr(&quot;test string&quot;, 6, 3), &quot;v2&quot;: substr1(&quot;test string&quot;, 6, 3) };
2808</pre></div></div>
2809</li>
2810<li>
2811
2812<p>The expected result is:</p>
2813
2814<div>
2815<div>
2816<pre class="source">{ &quot;v1&quot;: &quot;tri&quot;, &quot;v2&quot;: &quot;str&quot; }
2817</pre></div></div>
2818</li>
2819</ul>
2820<p>The function has an alias <tt>substring</tt>.</p></div>
2821<div class="section">
2822<h3><a name="trim"></a>trim</h3>
2823<ul>
2824
2825<li>
2826
2827<p>Syntax:</p>
2828
2829<div>
2830<div>
2831<pre class="source">trim(string[, chars]);
2832</pre></div></div>
2833</li>
2834<li>
2835
2836<p>Returns a new string with all leading and trailing characters that appear in <tt>chars</tt> removed. By default, white space is the character to trim. Note that here one character means one code point. For example, the emoji 4-people-family notation &#x201c;&#x1f469;&#x200d;&#x1f469;&#x200d;&#x1f467;&#x200d;&#x1f466;&#x201d; contains 7 code points, and it is possible to trim a few code points (such as a 2-people-family &#x201c;&#x1f468;&#x200d;&#x1f466;&#x201d;) from it. See the following example for more details.</p>
2837</li>
2838<li>Arguments:
2839<ul>
2840
2841<li><tt>string</tt> : a <tt>string</tt> to be trimmed,</li>
2842<li><tt>chars</tt> : a <tt>string</tt> that contains characters that are used to trim.</li>
2843</ul>
2844</li>
2845<li>Return Value:
2846<ul>
2847
2848<li>a trimmed, new <tt>string</tt>,</li>
2849<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
2850<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2851<li>any other non-string input value will cause a type error.</li>
2852</ul>
2853</li>
2854<li>Related functions: see <tt>ltrim()</tt>, <tt>rtrim()</tt></li>
2855<li>
2856
2857<p>Example:</p>
2858
2859<div>
2860<div>
2861<pre class="source">trim(&quot;i like x-phone&quot;, &quot;xphoen&quot;);
2862</pre></div></div>
2863</li>
2864<li>
2865
2866<p>The expected result is:</p>
2867
2868<div>
2869<div>
2870<pre class="source">&quot; like &quot;
2871</pre></div></div>
2872</li>
2873<li>
2874
2875<p>Example with multi-codepoint notation (trim the man and boy from the family of man, woman, girl and boy):</p>
2876<p>trim(&#x201c;&#x1f468;&#x200d;&#x1f469;&#x200d;&#x1f467;&#x200d;&#x1f466;&#x201d;, &#x201c;&#x1f468;&#x200d;&#x1f466;&#x201d;)</p>
2877</li>
2878<li>
2879
2880<p>The expected result is (only woman and girl are left in the family):</p>
2881
2882<div>
2883<div>
2884<pre class="source"> &quot;&#x1f469;&#x200d;&#x1f467;&quot;
2885</pre></div></div>
2886</li>
2887</ul></div>
2888<div class="section">
2889<h3><a name="upper"></a>upper</h3>
2890<ul>
2891
2892<li>
2893
2894<p>Syntax:</p>
2895
2896<div>
2897<div>
2898<pre class="source">upper(string)
2899</pre></div></div>
2900</li>
2901<li>
2902
2903<p>Converts a given string <tt>string</tt> to its uppercase form.</p>
2904</li>
2905<li>Arguments:
2906<ul>
2907
2908<li><tt>string</tt> : a <tt>string</tt> to be converted.</li>
2909</ul>
2910</li>
2911<li>Return Value:
2912<ul>
2913
2914<li>a <tt>string</tt> as the uppercase form of the given <tt>string</tt>,</li>
2915<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
2916<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
2917<li>any other non-string input value will cause a type error.</li>
2918</ul>
2919</li>
2920<li>
2921
2922<p>Example:</p>
2923
2924<div>
2925<div>
2926<pre class="source">upper(&quot;hello&quot;)
2927</pre></div></div>
2928</li>
2929<li>
2930
2931<p>The expected result is:</p>
2932
2933<div>
2934<div>
2935<pre class="source">&quot;HELLO&quot;
2936</pre></div></div>
2937</li>
2938</ul><!--
2939 ! Licensed to the Apache Software Foundation (ASF) under one
2940 ! or more contributor license agreements. See the NOTICE file
2941 ! distributed with this work for additional information
2942 ! regarding copyright ownership. The ASF licenses this file
2943 ! to you under the Apache License, Version 2.0 (the
2944 ! "License"); you may not use this file except in compliance
2945 ! with the License. You may obtain a copy of the License at
2946 !
2947 ! http://www.apache.org/licenses/LICENSE-2.0
2948 !
2949 ! Unless required by applicable law or agreed to in writing,
2950 ! software distributed under the License is distributed on an
2951 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
2952 ! KIND, either express or implied. See the License for the
2953 ! specific language governing permissions and limitations
2954 ! under the License.
2955 !-->
2956</div>
2957<div class="section">
2958<h3><a name="string_concat"></a>string_concat</h3>
2959<ul>
2960
2961<li>
2962
2963<p>Syntax:</p>
2964
2965<div>
2966<div>
2967<pre class="source">string_concat(array)
2968</pre></div></div>
2969</li>
2970<li>
2971
2972<p>Concatenates an array of strings <tt>array</tt> into a single string.</p>
2973</li>
2974<li>Arguments:
2975<ul>
2976
2977<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>
2978</ul>
2979</li>
2980<li>Return Value:
2981<ul>
2982
2983<li>the concatenated <tt>string</tt> value,</li>
2984<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
2985<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
2986<li><tt>missing</tt> if any element in the input array is <tt>missing</tt>,</li>
2987<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>
2988<li>any other non-array input value or non-integer element in the input array will cause a type error.</li>
2989</ul>
2990</li>
2991<li>
2992
2993<p>Example:</p>
2994
2995<div>
2996<div>
2997<pre class="source">string_concat([&quot;ASTERIX&quot;, &quot; &quot;, &quot;ROCKS!&quot;]);
2998</pre></div></div>
2999</li>
3000<li>
3001
3002<p>The expected result is:</p>
3003
3004<div>
3005<div>
3006<pre class="source">&quot;ASTERIX ROCKS!&quot;
3007</pre></div></div>
3008</li>
3009</ul></div>
3010<div class="section">
3011<h3><a name="string_join"></a>string_join</h3>
3012<ul>
3013
3014<li>
3015
3016<p>Syntax:</p>
3017
3018<div>
3019<div>
3020<pre class="source">string_join(array, string)
3021</pre></div></div>
3022</li>
3023<li>
3024
3025<p>Joins an array or multiset of strings <tt>array</tt> with the given separator <tt>string</tt> into a single string.</p>
3026</li>
3027<li>Arguments:
3028<ul>
3029
3030<li><tt>array</tt> : an <tt>array</tt> or <tt>multiset</tt> of strings (could be <tt>null</tt>) to be joined.</li>
3031<li><tt>string</tt> : a <tt>string</tt> to serve as the separator.</li>
3032</ul>
3033</li>
3034<li>Return Value:
3035<ul>
3036
3037<li>the joined <tt>string</tt>,</li>
3038<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3039<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3040<li><tt>missing</tt> if the first argument array contains a <tt>missing</tt>,</li>
3041<li><tt>null</tt> if the first argument array contains a <tt>null</tt> but does not contain a <tt>missing</tt>,</li>
3042<li>a type error will be raised if:
3043<ul>
3044
3045<li>the first argument is any other non-array value, or contains any other non-string value,</li>
3046<li>or, the second argument is any other non-string value.</li>
3047</ul>
3048</li>
3049</ul>
3050</li>
3051<li>
3052
3053<p>Example:</p>
3054
3055<div>
3056<div>
3057<pre class="source">string_join([&quot;ASTERIX&quot;, &quot;ROCKS~&quot;], &quot;!! &quot;);
3058</pre></div></div>
3059</li>
3060<li>
3061
3062<p>The expected result is:</p>
3063
3064<div>
3065<div>
3066<pre class="source">&quot;ASTERIX!! ROCKS~&quot;
3067</pre></div></div>
3068</li>
3069</ul></div>
3070<div class="section">
3071<h3><a name="string_to_codepoint"></a>string_to_codepoint</h3>
3072<ul>
3073
3074<li>
3075
3076<p>Syntax:</p>
3077
3078<div>
3079<div>
3080<pre class="source">string_to_codepoint(string)
3081</pre></div></div>
3082</li>
3083<li>
3084
3085<p>Converts the string <tt>string</tt> to its code_based representation.</p>
3086</li>
3087<li>Arguments:
3088<ul>
3089
3090<li><tt>string</tt> : a <tt>string</tt> that will be converted.</li>
3091</ul>
3092</li>
3093<li>Return Value:
3094<ul>
3095
3096<li>an <tt>array</tt> of the code points for the string <tt>string</tt>,</li>
3097<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
3098<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
3099<li>any other non-string input value will cause a type error.</li>
3100</ul>
3101</li>
3102<li>
3103
3104<p>Example:</p>
3105
3106<div>
3107<div>
3108<pre class="source">string_to_codepoint(&quot;Hello ASTERIX!&quot;);
3109</pre></div></div>
3110</li>
3111<li>
3112
3113<p>The expected result is:</p>
3114
3115<div>
3116<div>
3117<pre class="source">[ 72, 101, 108, 108, 111, 32, 65, 83, 84, 69, 82, 73, 88, 33 ]
3118</pre></div></div>
3119</li>
3120</ul></div>
3121<div class="section">
3122<h3><a name="codepoint_to_string"></a>codepoint_to_string</h3>
3123<ul>
3124
3125<li>
3126
3127<p>Syntax:</p>
3128
3129<div>
3130<div>
3131<pre class="source">codepoint_to_string(array)
3132</pre></div></div>
3133</li>
3134<li>
3135
3136<p>Converts the ordered code_based representation <tt>array</tt> to the corresponding string.</p>
3137</li>
3138<li>Arguments:
3139<ul>
3140
3141<li><tt>array</tt> : an <tt>array</tt> of integer code_points.</li>
3142</ul>
3143</li>
3144<li>Return Value:
3145<ul>
3146
3147<li>a <tt>string</tt> representation of <tt>array</tt>.</li>
3148<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
3149<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
3150<li><tt>missing</tt> if any element in the input array is <tt>missing</tt>,</li>
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<li>any other non-array input value or non-integer element in the input array will cause a type error.</li>
3153</ul>
3154</li>
3155<li>
3156
3157<p>Example:</p>
3158
3159<div>
3160<div>
3161<pre class="source">codepoint_to_string([72, 101, 108, 108, 111, 32, 65, 83, 84, 69, 82, 73, 88, 33]);
3162</pre></div></div>
3163</li>
3164<li>
3165
3166<p>The expected result is:</p>
3167
3168<div>
3169<div>
3170<pre class="source">&quot;Hello ASTERIX!&quot;
3171</pre></div></div>
3172</li>
3173</ul></div>
3174<div class="section">
3175<h3><a name="substring_before"></a>substring_before</h3>
3176<ul>
3177
3178<li>
3179
3180<p>Syntax:</p>
3181
3182<div>
3183<div>
3184<pre class="source">substring_before(string, string_pattern)
3185</pre></div></div>
3186</li>
3187<li>
3188
3189<p>Returns the substring from the given string <tt>string</tt> before the given pattern <tt>string_pattern</tt>.</p>
3190</li>
3191<li>Arguments:
3192<ul>
3193
3194<li><tt>string</tt> : a <tt>string</tt> to be extracted.</li>
3195<li><tt>string_pattern</tt> : a <tt>string</tt> pattern to be searched.</li>
3196</ul>
3197</li>
3198<li>Return Value:
3199<ul>
3200
3201<li>a <tt>string</tt> that represents the substring,</li>
3202<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3203<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3204<li>any other non-string input value will cause a type error.</li>
3205</ul>
3206</li>
3207<li>
3208
3209<p>Example:</p>
3210
3211<div>
3212<div>
3213<pre class="source">substring_before(&quot; like x-phone&quot;, &quot;x-phone&quot;);
3214</pre></div></div>
3215</li>
3216<li>
3217
3218<p>The expected result is:</p>
3219
3220<div>
3221<div>
3222<pre class="source">&quot; like &quot;
3223</pre></div></div>
3224</li>
3225</ul></div>
3226<div class="section">
3227<h3><a name="substring_after"></a>substring_after</h3>
3228<ul>
3229
3230<li>
3231
3232<p>Syntax:</p>
3233<p>substring_after(string, string_pattern);</p>
3234</li>
3235<li>
3236
3237<p>Returns the substring from the given string <tt>string</tt> after the given pattern <tt>string_pattern</tt>.</p>
3238</li>
3239<li>Arguments:
3240<ul>
3241
3242<li><tt>string</tt> : a <tt>string</tt> to be extracted.</li>
3243<li><tt>string_pattern</tt> : a <tt>string</tt> pattern to be searched.</li>
3244</ul>
3245</li>
3246<li>Return Value:
3247<ul>
3248
3249<li>a <tt>string</tt> that represents the substring,</li>
3250<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3251<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3252<li>any other non-string input value will cause a type error.</li>
3253</ul>
3254</li>
3255<li>
3256
3257<p>Example:</p>
3258
3259<div>
3260<div>
3261<pre class="source">substring_after(&quot; like x-phone&quot;, &quot;xph&quot;);
3262</pre></div></div>
3263</li>
3264<li>
3265
3266<p>The expected result is:</p>
3267
3268<div>
3269<div>
3270<pre class="source">&quot;one&quot;
3271</pre></div></div>
3272</li>
3273</ul><!--
3274 ! Licensed to the Apache Software Foundation (ASF) under one
3275 ! or more contributor license agreements. See the NOTICE file
3276 ! distributed with this work for additional information
3277 ! regarding copyright ownership. The ASF licenses this file
3278 ! to you under the Apache License, Version 2.0 (the
3279 ! "License"); you may not use this file except in compliance
3280 ! with the License. You may obtain a copy of the License at
3281 !
3282 ! http://www.apache.org/licenses/LICENSE-2.0
3283 !
3284 ! Unless required by applicable law or agreed to in writing,
3285 ! software distributed under the License is distributed on an
3286 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
3287 ! KIND, either express or implied. See the License for the
3288 ! specific language governing permissions and limitations
3289 ! under the License.
3290 !-->
3291</div></div>
3292<div class="section">
3293<h2><a name="Binary_Functions"></a><a name="BinaryFunctions" id="BinaryFunctions">Binary Functions</a></h2>
3294<div class="section">
3295<h3><a name="parse_binary"></a>parse_binary</h3>
3296<ul>
3297
3298<li>
3299
3300<p>Syntax:</p>
3301<p>parse_binary(string, encoding)</p>
3302</li>
3303<li>
3304
3305<p>Creates a <tt>binary</tt> from an string encoded in <tt>encoding</tt> format.</p>
3306</li>
3307<li>Arguments:
3308<ul>
3309
3310<li><tt>string</tt> : an encoded <tt>string</tt>,</li>
3311<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>
3312</ul>
3313</li>
3314<li>Return Value:
3315<ul>
3316
3317<li>a <tt>binary</tt> that is decoded from the given <tt>string</tt>,</li>
3318<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3319<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3320<li>any other non-string input value will cause a type error.</li>
3321</ul>
3322</li>
3323<li>
3324
3325<p>Example:</p>
3326<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>
3327</li>
3328<li>
3329
3330<p>The expected result is:</p>
3331<p>[ hex(&#x201c;ABCDEF0123456789&#x201d;), hex(&#x201c;ABCDEF0123456789&#x201d;), hex(&#x201c;4173746572697801&#x201d;) ]</p>
3332</li>
3333</ul></div>
3334<div class="section">
3335<h3><a name="print_binary"></a>print_binary</h3>
3336<ul>
3337
3338<li>
3339
3340<p>Syntax:</p>
3341<p>print_binary(binary, encoding)</p>
3342</li>
3343<li>
3344
3345<p>Prints a <tt>binary</tt> to the required encoding <tt>string</tt> format.</p>
3346</li>
3347<li>Arguments:
3348<ul>
3349
3350<li><tt>binary</tt> : a <tt>binary</tt> data need to be printed.</li>
3351<li><tt>encoding</tt> : a string notation specifies the expected encoding type. Currently we support <tt>hex</tt> and <tt>base64</tt> format.</li>
3352</ul>
3353</li>
3354<li>Return Value:
3355<ul>
3356
3357<li>a <tt>string</tt> that represents the encoded format of a <tt>binary</tt>,</li>
3358<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3359<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3360<li>any other non-string input value will cause a type error.</li>
3361</ul>
3362</li>
3363<li>
3364
3365<p>Example:</p>
3366
3367<div>
3368<div>
3369<pre class="source">[ print_binary(hex(&quot;ABCDEF0123456789&quot;), &quot;base64&quot;), print_binary(base64(&quot;q83vASNFZ4k=&quot;), &quot;hex&quot;) ]
3370</pre></div></div>
3371</li>
3372<li>
3373
3374<p>The expected result are:</p>
3375
3376<div>
3377<div>
3378<pre class="source">[ &quot;q83vASNFZ4k=&quot;, &quot;ABCDEF0123456789&quot; ]
3379</pre></div></div>
3380</li>
3381</ul></div>
3382<div class="section">
3383<h3><a name="binary_length"></a>binary_length</h3>
3384<ul>
3385
3386<li>
3387
3388<p>Syntax:</p>
3389<p>binary_length(binary)</p>
3390</li>
3391<li>
3392
3393<p>Returns the number of bytes storing the binary data.</p>
3394</li>
3395<li>Arguments:
3396<ul>
3397
3398<li><tt>binary</tt> : a <tt>binary</tt> value to be checked.</li>
3399</ul>
3400</li>
3401<li>Return Value:
3402<ul>
3403
3404<li>an <tt>bigint</tt> that represents the number of bytes,</li>
3405<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
3406<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
3407<li>any other non-binary input value will cause a type error.</li>
3408</ul>
3409</li>
3410<li>
3411
3412<p>Example:</p>
3413
3414<div>
3415<div>
3416<pre class="source">binary_length(hex(&quot;00AA&quot;))
3417</pre></div></div>
3418</li>
3419<li>
3420
3421<p>The expected result is:</p>
3422<p>2</p>
3423</li>
3424</ul></div>
3425<div class="section">
3426<h3><a name="sub_binary"></a>sub_binary</h3>
3427<ul>
3428
3429<li>
3430
3431<p>Syntax:</p>
3432<p>sub_binary(binary, offset[, length])</p>
3433</li>
3434<li>
3435
3436<p>Returns the sub binary from the given <tt>binary</tt> based on the given start offset with the optional <tt>length</tt>.</p>
3437</li>
3438<li>Arguments:
3439<ul>
3440
3441<li><tt>binary</tt> : a <tt>binary</tt> to be extracted,</li>
3442<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> (starting at 0),</li>
3443<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>
3444</ul>
3445</li>
3446<li>Return Value:
3447<ul>
3448
3449<li>a <tt>binary</tt> that represents the sub binary,</li>
3450<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3451<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3452<li>a type error will be raised if:
3453<ul>
3454
3455<li>the first argument is any other non-binary value,</li>
3456<li>or, the second argument is any other non-integer value,</li>
3457<li>or, the third argument is any other non-integer value, if it is present.</li>
3458</ul>
3459</li>
3460</ul>
3461</li>
3462<li>
3463
3464<p>Example:</p>
3465
3466<div>
3467<div>
3468<pre class="source">sub_binary(hex(&quot;AABBCCDD&quot;), 4);
3469</pre></div></div>
3470</li>
3471<li>
3472
3473<p>The expected result is</p>
3474
3475<div>
3476<div>
3477<pre class="source">hex(&quot;DD&quot;)
3478</pre></div></div>
3479</li>
3480</ul></div>
3481<div class="section">
3482<h3><a name="binary_concat"></a>binary_concat</h3>
3483<ul>
3484
3485<li>
3486
3487<p>Syntax:</p>
3488<p>binary_concat(array)</p>
3489</li>
3490<li>
3491
3492<p>Concatenates a binary <tt>array</tt> or <tt>multiset</tt> into a single binary.</p>
3493</li>
3494<li>Arguments:
3495<ul>
3496
3497<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>
3498</ul>
3499</li>
3500<li>Return Value :
3501<ul>
3502
3503<li>the concatenated <tt>binary</tt> value,</li>
3504<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
3505<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
3506<li><tt>missing</tt> if any element in the input array is <tt>missing</tt>,</li>
3507<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>
3508<li>any other non-array input value or non-binary element in the input array will cause a type error.</li>
3509</ul>
3510</li>
3511<li>
3512
3513<p>Example:</p>
3514<p>binary_concat([hex(&#x201c;42&#x201d;), hex(&quot;&quot;), hex(&#x2018;42&#x2019;)]);</p>
3515</li>
3516<li>
3517
3518<p>The expected result is</p>
3519<p>hex(&#x201c;4242&#x201d;)</p>
3520</li>
3521</ul><!--
3522 ! Licensed to the Apache Software Foundation (ASF) under one
3523 ! or more contributor license agreements. See the NOTICE file
3524 ! distributed with this work for additional information
3525 ! regarding copyright ownership. The ASF licenses this file
3526 ! to you under the Apache License, Version 2.0 (the
3527 ! "License"); you may not use this file except in compliance
3528 ! with the License. You may obtain a copy of the License at
3529 !
3530 ! http://www.apache.org/licenses/LICENSE-2.0
3531 !
3532 ! Unless required by applicable law or agreed to in writing,
3533 ! software distributed under the License is distributed on an
3534 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
3535 ! KIND, either express or implied. See the License for the
3536 ! specific language governing permissions and limitations
3537 ! under the License.
3538 !-->
3539</div></div>
3540<div class="section">
3541<h2><a name="Spatial_Functions"></a><a name="SpatialFunctions" id="SpatialFunctions">Spatial Functions</a></h2>
3542<div class="section">
3543<h3><a name="create_point"></a>create_point</h3>
3544<ul>
3545
3546<li>
3547
3548<p>Syntax:</p>
3549
3550<div>
3551<div>
3552<pre class="source">create_point(x, y)
3553</pre></div></div>
3554</li>
3555<li>
3556
3557<p>Creates the primitive type <tt>point</tt> using an <tt>x</tt> and <tt>y</tt> value.</p>
3558</li>
3559<li>Arguments:</li>
3560<li><tt>x</tt> : a <tt>double</tt> that represents the x-coordinate,</li>
3561<li><tt>y</tt> : a <tt>double</tt> that represents the y-coordinate.</li>
3562<li>Return Value:</li>
3563<li>a <tt>point</tt> representing the ordered pair (<tt>x</tt>, <tt>y</tt>),</li>
3564<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3565<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3566<li>any other non-double input value will cause a type error.</li>
3567<li>
3568
3569<p>Example:</p>
3570
3571<div>
3572<div>
3573<pre class="source">{ &quot;point&quot;: create_point(30.0,70.0) };
3574</pre></div></div>
3575</li>
3576<li>
3577
3578<p>The expected result is:</p>
3579
3580<div>
3581<div>
3582<pre class="source">{ &quot;point&quot;: point(&quot;30.0,70.0&quot;) }
3583</pre></div></div>
3584</li>
3585</ul></div>
3586<div class="section">
3587<h3><a name="create_line"></a>create_line</h3>
3588<ul>
3589
3590<li>
3591
3592<p>Syntax:</p>
3593
3594<div>
3595<div>
3596<pre class="source">create_line(point1, point2)
3597</pre></div></div>
3598</li>
3599<li>
3600
3601<p>Creates the primitive type <tt>line</tt> using <tt>point1</tt> and <tt>point2</tt>.</p>
3602</li>
3603<li>Arguments:
3604<ul>
3605
3606<li><tt>point1</tt> : a <tt>point</tt> that represents the start point of the line.</li>
3607<li><tt>point2</tt> : a <tt>point</tt> that represents the end point of the line.</li>
3608</ul>
3609</li>
3610<li>Return Value:
3611<ul>
3612
3613<li>a spatial <tt>line</tt> created using the points provided in <tt>point1</tt> and <tt>point2</tt>,</li>
3614<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3615<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3616<li>any other non-point input value will cause a type error.</li>
3617</ul>
3618</li>
3619<li>
3620
3621<p>Example:</p>
3622
3623<div>
3624<div>
3625<pre class="source">{ &quot;line&quot;: create_line(create_point(30.0,70.0), create_point(50.0,90.0)) };
3626</pre></div></div>
3627</li>
3628<li>
3629
3630<p>The expected result is:</p>
3631
3632<div>
3633<div>
3634<pre class="source">{ &quot;line&quot;: line(&quot;30.0,70.0 50.0,90.0&quot;) }
3635</pre></div></div>
3636</li>
3637</ul></div>
3638<div class="section">
3639<h3><a name="create_rectangle"></a>create_rectangle</h3>
3640<ul>
3641
3642<li>
3643
3644<p>Syntax:</p>
3645
3646<div>
3647<div>
3648<pre class="source">create_rectangle(point1, point2)
3649</pre></div></div>
3650</li>
3651<li>
3652
3653<p>Creates the primitive type <tt>rectangle</tt> using <tt>point1</tt> and <tt>point2</tt>.</p>
3654</li>
3655<li>Arguments:
3656<ul>
3657
3658<li><tt>point1</tt> : a <tt>point</tt> that represents the lower_left point of the rectangle.</li>
3659<li><tt>point2</tt> : a <tt>point</tt> that represents the upper_right point of the rectangle.</li>
3660</ul>
3661</li>
3662<li>Return Value:
3663<ul>
3664
3665<li>a spatial <tt>rectangle</tt> created using the points provided in <tt>point1</tt> and <tt>point2</tt>,</li>
3666<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3667<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3668<li>any other non-point input value will cause a type error.</li>
3669</ul>
3670</li>
3671<li>
3672
3673<p>Example:</p>
3674
3675<div>
3676<div>
3677<pre class="source">{ &quot;rectangle&quot;: create_rectangle(create_point(30.0,70.0), create_point(50.0,90.0)) };
3678</pre></div></div>
3679</li>
3680<li>
3681
3682<p>The expected result is:</p>
3683
3684<div>
3685<div>
3686<pre class="source">{ &quot;rectangle&quot;: rectangle(&quot;30.0,70.0 50.0,90.0&quot;) }
3687</pre></div></div>
3688</li>
3689</ul></div>
3690<div class="section">
3691<h3><a name="create_circle"></a>create_circle</h3>
3692<ul>
3693
3694<li>
3695
3696<p>Syntax:</p>
3697
3698<div>
3699<div>
3700<pre class="source">create_circle(point, radius)
3701</pre></div></div>
3702</li>
3703<li>
3704
3705<p>Creates the primitive type <tt>circle</tt> using <tt>point</tt> and <tt>radius</tt>.</p>
3706</li>
3707<li>Arguments:
3708<ul>
3709
3710<li><tt>point</tt> : a <tt>point</tt> that represents the center of the circle.</li>
3711<li><tt>radius</tt> : a <tt>double</tt> that represents the radius of the circle.</li>
3712</ul>
3713</li>
3714<li>Return Value:
3715<ul>
3716
3717<li>a spatial <tt>circle</tt> created using the center point and the radius provided in <tt>point</tt> and <tt>radius</tt>.</li>
3718<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3719<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3720<li>a type error will be raised if:
3721<ul>
3722
3723<li>the first argument is any other non-point value,</li>
3724<li>or, the second argument is any other non-double value.</li>
3725</ul>
3726</li>
3727</ul>
3728</li>
3729<li>
3730
3731<p>Example:</p>
3732
3733<div>
3734<div>
3735<pre class="source">{ &quot;circle&quot;: create_circle(create_point(30.0,70.0), 5.0) }
3736</pre></div></div>
3737</li>
3738<li>
3739
3740<p>The expected result is:</p>
3741
3742<div>
3743<div>
3744<pre class="source">{ &quot;circle&quot;: circle(&quot;30.0,70.0 5.0&quot;) }
3745</pre></div></div>
3746</li>
3747</ul></div>
3748<div class="section">
3749<h3><a name="create_polygon"></a>create_polygon</h3>
3750<ul>
3751
3752<li>
3753
3754<p>Syntax:</p>
3755
3756<div>
3757<div>
3758<pre class="source">create_polygon(array)
3759</pre></div></div>
3760</li>
3761<li>
3762
3763<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>
3764</li>
3765<li>Arguments:
3766<ul>
3767
3768<li><tt>array</tt> : an array of doubles representing the points of the polygon.</li>
3769</ul>
3770</li>
3771<li>Return Value:
3772<ul>
3773
3774<li>a <tt>polygon</tt>, represents a spatial simple polygon created using the points provided in <tt>array</tt>.</li>
3775<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
3776<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
3777<li><tt>missing</tt> if any element in the input array is <tt>missing</tt>,</li>
3778<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>
3779<li>any other non-array input value or non-double element in the input array will cause a type error.</li>
3780</ul>
3781</li>
3782<li>
3783
3784<p>Example:</p>
3785
3786<div>
3787<div>
3788<pre class="source">{ &quot;polygon&quot;: create_polygon([1.0,1.0,2.0,2.0,3.0,3.0,4.0,4.0]) };
3789</pre></div></div>
3790</li>
3791<li>
3792
3793<p>The expected result is:</p>
3794
3795<div>
3796<div>
3797<pre class="source">{ &quot;polygon&quot;: polygon(&quot;1.0,1.0 2.0,2.0 3.0,3.0 4.0,4.0&quot;) }
3798</pre></div></div>
3799</li>
3800</ul></div>
3801<div class="section">
3802<h3><a name="get_x.2Fget_y"></a>get_x/get_y</h3>
3803<ul>
3804
3805<li>
3806
3807<p>Syntax:</p>
3808
3809<div>
3810<div>
3811<pre class="source">get_x(point) or get_y(point)
3812</pre></div></div>
3813</li>
3814<li>
3815
3816<p>Returns the x or y coordinates of a point <tt>point</tt>.</p>
3817</li>
3818<li>Arguments:
3819<ul>
3820
3821<li><tt>point</tt> : a <tt>point</tt>.</li>
3822</ul>
3823</li>
3824<li>Return Value:
3825<ul>
3826
3827<li>a <tt>double</tt> representing the x or y coordinates of the point <tt>point</tt>,</li>
3828<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
3829<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
3830<li>any other non-point input value will cause a type error.</li>
3831</ul>
3832</li>
3833<li>
3834
3835<p>Example:</p>
3836
3837<div>
3838<div>
3839<pre class="source">{ &quot;x_coordinate&quot;: get_x(create_point(2.3,5.0)), &quot;y_coordinate&quot;: get_y(create_point(2.3,5.0)) };
3840</pre></div></div>
3841</li>
3842<li>
3843
3844<p>The expected result is:</p>
3845
3846<div>
3847<div>
3848<pre class="source">{ &quot;x_coordinate&quot;: 2.3, &quot;y_coordinate&quot;: 5.0 }
3849</pre></div></div>
3850</li>
3851</ul></div>
3852<div class="section">
3853<h3><a name="get_points"></a>get_points</h3>
3854<ul>
3855
3856<li>
3857
3858<p>Syntax:</p>
3859
3860<div>
3861<div>
3862<pre class="source">get_points(spatial_object)
3863</pre></div></div>
3864</li>
3865<li>
3866
3867<p>Returns an ordered array of the points forming the spatial object <tt>spatial_object</tt>.</p>
3868</li>
3869<li>Arguments:
3870<ul>
3871
3872<li><tt>spatial_object</tt> : a <tt>point</tt>, <tt>line</tt>, <tt>rectangle</tt>, <tt>circle</tt>, or <tt>polygon</tt>.</li>
3873</ul>
3874</li>
3875<li>Return Value:
3876<ul>
3877
3878<li>an <tt>array</tt> of the points forming the spatial object <tt>spatial_object</tt>,</li>
3879<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
3880<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
3881<li>any other non-spatial-object input value will cause a type error.</li>
3882</ul>
3883</li>
3884<li>
3885
3886<p>Example:</p>
3887
3888<div>
3889<div>
3890<pre class="source">get_points(create_polygon([1.0,1.0,2.0,2.0,3.0,3.0,4.0,4.0]))
3891</pre></div></div>
3892</li>
3893<li>
3894
3895<p>The expected result is:</p>
3896
3897<div>
3898<div>
3899<pre class="source">[ 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;) ]
3900</pre></div></div>
3901</li>
3902</ul></div>
3903<div class="section">
3904<h3><a name="get_center.2Fget_radius"></a>get_center/get_radius</h3>
3905<ul>
3906
3907<li>
3908
3909<p>Syntax:</p>
3910
3911<div>
3912<div>
3913<pre class="source">get_center(circle_expression) or get_radius(circle_expression)
3914</pre></div></div>
3915</li>
3916<li>
3917
3918<p>Returns the center and the radius of a circle <tt>circle_expression</tt>, respectively.</p>
3919</li>
3920<li>Arguments:
3921<ul>
3922
3923<li><tt>circle_expression</tt> : a <tt>circle</tt>.</li>
3924</ul>
3925</li>
3926<li>Return Value:
3927<ul>
3928
3929<li>a <tt>point</tt> or <tt>double</tt>, represent the center or radius of the circle <tt>circle_expression</tt>.</li>
3930<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
3931<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
3932<li>any other non-circle input value will cause a type error.</li>
3933</ul>
3934</li>
3935<li>
3936
3937<p>Example:</p>
3938
3939<div>
3940<div>
3941<pre class="source">{
3942 &quot;circle_radius&quot;: get_radius(create_circle(create_point(6.0,3.0), 1.0)),
3943 &quot;circle_center&quot;: get_center(create_circle(create_point(6.0,3.0), 1.0))
3944};
3945</pre></div></div>
3946</li>
3947<li>
3948
3949<p>The expected result is:</p>
3950
3951<div>
3952<div>
3953<pre class="source">{ &quot;circle_radius&quot;: 1.0, &quot;circle_center&quot;: point(&quot;6.0,3.0&quot;) }
3954</pre></div></div>
3955</li>
3956</ul></div>
3957<div class="section">
3958<h3><a name="spatial_distance"></a>spatial_distance</h3>
3959<ul>
3960
3961<li>
3962
3963<p>Syntax:</p>
3964
3965<div>
3966<div>
3967<pre class="source">spatial_distance(point1, point2)
3968</pre></div></div>
3969</li>
3970<li>
3971
3972<p>Returns the Euclidean distance between <tt>point1</tt> and <tt>point2</tt>.</p>
3973</li>
3974<li>Arguments:
3975<ul>
3976
3977<li><tt>point1</tt> : a <tt>point</tt>.</li>
3978<li><tt>point2</tt> : a <tt>point</tt>.</li>
3979</ul>
3980</li>
3981<li>Return Value:
3982<ul>
3983
3984<li>a <tt>double</tt> as the Euclidean distance between <tt>point1</tt> and <tt>point2</tt>.</li>
3985<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
3986<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
3987<li>any other non-point input value will cause a type error.</li>
3988</ul>
3989</li>
3990<li>
3991
3992<p>Example:</p>
3993
3994<div>
3995<div>
3996<pre class="source">spatial_distance(point(&quot;47.44,80.65&quot;), create_point(30.0,70.0));
3997</pre></div></div>
3998</li>
3999<li>
4000
4001<p>The expected result is:</p>
4002
4003<div>
4004<div>
4005<pre class="source">20.434678857275934
4006</pre></div></div>
4007</li>
4008</ul></div>
4009<div class="section">
4010<h3><a name="spatial_area"></a>spatial_area</h3>
4011<ul>
4012
4013<li>
4014
4015<p>Syntax:</p>
4016
4017<div>
4018<div>
4019<pre class="source">spatial_area(spatial_2d_expression)
4020</pre></div></div>
4021</li>
4022<li>
4023
4024<p>Returns the spatial area of <tt>spatial_2d_expression</tt>.</p>
4025</li>
4026<li>Arguments:
4027<ul>
4028
4029<li><tt>spatial_2d_expression</tt> : a <tt>rectangle</tt>, <tt>circle</tt>, or <tt>polygon</tt>.</li>
4030</ul>
4031</li>
4032<li>Return Value:
4033<ul>
4034
4035<li>a <tt>double</tt> representing the area of <tt>spatial_2d_expression</tt>.</li>
4036<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
4037<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
4038<li>any other non-2d-spatial-object will cause a type error.</li>
4039</ul>
4040</li>
4041<li>
4042
4043<p>Example:</p>
4044
4045<div>
4046<div>
4047<pre class="source">spatial_area(create_circle(create_point(0.0,0.0), 5.0));
4048</pre></div></div>
4049</li>
4050<li>
4051
4052<p>The expected result is:</p>
4053
4054<div>
4055<div>
4056<pre class="source">78.53981625
4057</pre></div></div>
4058</li>
4059</ul></div>
4060<div class="section">
4061<h3><a name="spatial_intersect"></a>spatial_intersect</h3>
4062<ul>
4063
4064<li>
4065
4066<p>Syntax:</p>
4067
4068<div>
4069<div>
4070<pre class="source">spatial_intersect(spatial_object1, spatial_object2)
4071</pre></div></div>
4072</li>
4073<li>
4074
4075<p>Checks whether <tt>@arg1</tt> and <tt>@arg2</tt> spatially intersect each other.</p>
4076</li>
4077<li>Arguments:
4078<ul>
4079
4080<li><tt>spatial_object1</tt> : a <tt>point</tt>, <tt>line</tt>, <tt>rectangle</tt>, <tt>circle</tt>, or <tt>polygon</tt>.</li>
4081<li><tt>spatial_object2</tt> : a <tt>point</tt>, <tt>line</tt>, <tt>rectangle</tt>, <tt>circle</tt>, or <tt>polygon</tt>.</li>
4082</ul>
4083</li>
4084<li>Return Value:
4085<ul>
4086
4087<li>a <tt>boolean</tt> representing whether <tt>spatial_object1</tt> and <tt>spatial_object2</tt> spatially overlap with each other,</li>
4088<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
4089<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
4090<li>any other non-spatial-object input value will cause a type error.</li>
4091</ul>
4092</li>
4093<li>
4094
4095<p>Example:</p>
4096
4097<div>
4098<div>
4099<pre class="source">spatial_intersect(point(&quot;39.28,70.48&quot;), create_rectangle(create_point(30.0,70.0), create_point(40.0,80.0)));
4100</pre></div></div>
4101</li>
4102<li>
4103
4104<p>The expected result is:</p>
4105
4106<div>
4107<div>
4108<pre class="source">true
4109</pre></div></div>
4110</li>
4111</ul></div>
4112<div class="section">
4113<h3><a name="spatial_cell"></a>spatial_cell</h3>
4114<ul>
4115
4116<li>
4117
4118<p>Syntax:</p>
4119
4120<div>
4121<div>
4122<pre class="source">spatial_cell(point1, point2, x_increment, y_increment)
4123</pre></div></div>
4124</li>
4125<li>
4126
4127<p>Returns the grid cell that <tt>point1</tt> belongs to.</p>
4128</li>
4129<li>Arguments:
4130<ul>
4131
4132<li><tt>point1</tt> : a <tt>point</tt> representing the point of interest that its grid cell will be returned.</li>
4133<li><tt>point2</tt> : a <tt>point</tt> representing the origin of the grid.</li>
4134<li><tt>x_increment</tt> : a <tt>double</tt>, represents X increments.</li>
4135<li><tt>y_increment</tt> : a <tt>double</tt>, represents Y increments.</li>
4136</ul>
4137</li>
4138<li>Return Value:
4139<ul>
4140
4141<li>a <tt>rectangle</tt> representing the grid cell that <tt>point1</tt> belongs to,</li>
4142<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
4143<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
4144<li>a type error will be raised if:
4145<ul>
4146
4147<li>the first or second argument is any other non-point value,</li>
4148<li>or, the second or third argument is any other non-double value.</li>
4149</ul>
4150</li>
4151</ul>
4152</li>
4153<li>
4154
4155<p>Example:</p>
4156
4157<div>
4158<div>
4159<pre class="source">spatial_cell(point(&quot;39.28,70.48&quot;), create_point(20.0,50.0), 5.5, 6.0);
4160</pre></div></div>
4161</li>
4162<li>
4163
4164<p>The expected result is:</p>
4165
4166<div>
4167<div>
4168<pre class="source">rectangle(&quot;36.5,68.0 42.0,74.0&quot;);
4169</pre></div></div>
4170</li>
4171</ul><!--
4172 ! Licensed to the Apache Software Foundation (ASF) under one
4173 ! or more contributor license agreements. See the NOTICE file
4174 ! distributed with this work for additional information
4175 ! regarding copyright ownership. The ASF licenses this file
4176 ! to you under the Apache License, Version 2.0 (the
4177 ! "License"); you may not use this file except in compliance
4178 ! with the License. You may obtain a copy of the License at
4179 !
4180 ! http://www.apache.org/licenses/LICENSE-2.0
4181 !
4182 ! Unless required by applicable law or agreed to in writing,
4183 ! software distributed under the License is distributed on an
4184 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
4185 ! KIND, either express or implied. See the License for the
4186 ! specific language governing permissions and limitations
4187 ! under the License.
4188 !-->
4189</div></div>
4190<div class="section">
4191<h2><a name="Similarity_Functions"></a><a name="SimilarityFunctions" id="SimilarityFunctions">Similarity Functions</a></h2>
4192<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>
4193<div class="section">
4194<h3><a name="edit_distance"></a>edit_distance</h3>
4195<ul>
4196
4197<li>
4198
4199<p>Syntax:</p>
4200
4201<div>
4202<div>
4203<pre class="source">edit_distance(expression1, expression2)
4204</pre></div></div>
4205</li>
4206<li>
4207
4208<p>Returns the edit distance of <tt>expression1</tt> and <tt>expression2</tt>.</p>
4209</li>
4210<li>Arguments:
4211<ul>
4212
4213<li><tt>expression1</tt> : a <tt>string</tt> or a homogeneous <tt>array</tt> of a comparable item type.</li>
4214<li><tt>expression2</tt> : The same type as <tt>expression1</tt>.</li>
4215</ul>
4216</li>
4217<li>Return Value:
4218<ul>
4219
4220<li>an <tt>bigint</tt> that represents the edit distance between <tt>expression1</tt> and <tt>expression2</tt>,</li>
4221<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
4222<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
4223<li>any other non-string input value will cause a type error.</li>
4224</ul>
4225</li>
4226<li>Note: an <a href="similarity.html#UsingIndexesToSupportSimilarityQueries">n_gram index</a> can be utilized for this function.</li>
4227<li>Example:
4228
4229<div>
4230<div>
4231<pre class="source">edit_distance(&quot;SuzannaTillson&quot;, &quot;Suzanna Tilson&quot;);
4232</pre></div></div>
4233</li>
4234<li>
4235
4236<p>The expected result is:</p>
4237
4238<div>
4239<div>
4240<pre class="source">2
4241</pre></div></div>
4242</li>
4243</ul></div>
4244<div class="section">
4245<h3><a name="edit_distance_check"></a>edit_distance_check</h3>
4246<ul>
4247
4248<li>
4249
4250<p>Syntax:</p>
4251
4252<div>
4253<div>
4254<pre class="source">edit_distance_check(expression1, expression2, threshold)
4255</pre></div></div>
4256</li>
4257<li>
4258
4259<p>Checks whether the edit distance of <tt>expression1</tt> and <tt>expression2</tt> is within a given threshold.</p>
4260</li>
4261<li>
4262
4263<p>Arguments:</p>
4264<ul>
4265
4266<li><tt>expression1</tt> : a <tt>string</tt> or a homogeneous <tt>array</tt> of a comparable item type.</li>
4267<li><tt>expression2</tt> : The same type as <tt>expression1</tt>.</li>
4268<li><tt>threshold</tt> : a <tt>bigint</tt> that represents the distance threshold.</li>
4269</ul>
4270</li>
4271<li>Return Value:
4272<ul>
4273
4274<li>an <tt>array</tt> with two items:
4275<ul>
4276
4277<li>The first item contains a <tt>boolean</tt> value representing whether the edit distance of <tt>expression1</tt> and <tt>expression2</tt> is within the given threshold.</li>
4278<li>The second item contains an <tt>integer</tt> that represents the edit distance of <tt>expression1</tt> and <tt>expression2</tt> if the first item is true.</li>
4279<li>If the first item is false, then the second item is set to 2147483647.</li>
4280</ul>
4281</li>
4282<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
4283<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
4284<li>a type error will be raised if:
4285<ul>
4286
4287<li>the first or second argument is any other non-string value,</li>
4288<li>or, the third argument is any other non-bigint value.</li>
4289</ul>
4290</li>
4291</ul>
4292</li>
4293<li>Note: an <a href="similarity.html#UsingIndexesToSupportSimilarityQueries">n_gram index</a> can be utilized for this function.</li>
4294<li>Example:
4295
4296<div>
4297<div>
4298<pre class="source">edit_distance_check(&quot;happy&quot;,&quot;hapr&quot;,2);
4299</pre></div></div>
4300</li>
4301<li>
4302
4303<p>The expected result is:</p>
4304
4305<div>
4306<div>
4307<pre class="source">[ true, 2 ]
4308</pre></div></div>
4309</li>
4310</ul></div>
4311<div class="section">
4312<h3><a name="edit_distance_contains"></a>edit_distance_contains</h3>
4313<ul>
4314
4315<li>
4316
4317<p>Syntax:</p>
4318
4319<div>
4320<div>
4321<pre class="source">edit_distance_contains(expression1, expression2, threshold)
4322</pre></div></div>
4323</li>
4324<li>
4325
4326<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>
4327</li>
4328<li>
4329
4330<p>Arguments:</p>
4331<ul>
4332
4333<li><tt>expression1</tt> : a <tt>string</tt> or a homogeneous <tt>array</tt> of a comparable item type.</li>
4334<li><tt>expression2</tt> : The same type as <tt>expression1</tt>.</li>
4335<li><tt>threshold</tt> : a <tt>bigint</tt> that represents the distance threshold.</li>
4336</ul>
4337</li>
4338<li>Return Value:
4339<ul>
4340
4341<li>an <tt>array</tt> with two items:
4342<ul>
4343
4344<li>The first item contains a <tt>boolean</tt> value representing whether <tt>expression1</tt> can contain <tt>expression2</tt>.</li>
4345<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>
4346</ul>
4347</li>
4348<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
4349<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
4350<li>a type error will be raised if:
4351<ul>
4352
4353<li>the first or second argument is any other non-string value,</li>
4354<li>or, the third argument is any other non-bigint value.</li>
4355</ul>
4356</li>
4357</ul>
4358</li>
4359<li>Note: an <a href="similarity.html#UsingIndexesToSupportSimilarityQueries">n_gram index</a> can be utilized for this function.</li>
4360<li>Example:
4361
4362<div>
4363<div>
4364<pre class="source">edit_distance_contains(&quot;happy&quot;,&quot;hapr&quot;,2);
4365</pre></div></div>
4366</li>
4367<li>
4368
4369<p>The expected result is:</p>
4370
4371<div>
4372<div>
4373<pre class="source">[ true, 1 ]
4374</pre></div></div>
4375</li>
4376</ul></div>
4377<div class="section">
4378<h3><a name="similarity_jaccard"></a>similarity_jaccard</h3>
4379<ul>
4380
4381<li>
4382
4383<p>Syntax:</p>
4384
4385<div>
4386<div>
4387<pre class="source">similarity_jaccard(array1, array2)
4388</pre></div></div>
4389</li>
4390<li>
4391
4392<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>
4393</li>
4394<li>Arguments:
4395<ul>
4396
4397<li><tt>array1</tt> : an <tt>array</tt> or <tt>multiset</tt>.</li>
4398<li><tt>array2</tt> : an <tt>array</tt> or <tt>multiset</tt>.</li>
4399</ul>
4400</li>
4401<li>Return Value:
4402<ul>
4403
4404<li>a <tt>float</tt> that represents the Jaccard similarity of <tt>array1</tt> and <tt>array2</tt>,</li>
4405<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
4406<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
4407<li><tt>missing</tt> if any element in any input array is <tt>missing</tt>,</li>
4408<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>
4409<li>any other non-array input value or non-integer element in any input array will cause a type error.</li>
4410</ul>
4411</li>
4412<li>
4413
4414<p>Note: a <a href="similarity.html#UsingIndexesToSupportSimilarityQueries">keyword index</a> can be utilized for this function.</p>
4415</li>
4416<li>Example:
4417
4418<div>
4419<div>
4420<pre class="source">similarity_jaccard([1,5,8,9], [1,5,9,10]);
4421</pre></div></div>
4422</li>
4423<li>
4424
4425<p>The expected result is:</p>
4426
4427<div>
4428<div>
4429<pre class="source">0.6
4430</pre></div></div>
4431</li>
4432</ul></div>
4433<div class="section">
4434<h3><a name="similarity_jaccard_check"></a>similarity_jaccard_check</h3>
4435<ul>
4436
4437<li>
4438
4439<p>Syntax:</p>
4440
4441<div>
4442<div>
4443<pre class="source">similarity_jaccard_check(array1, array2, threshold)
4444</pre></div></div>
4445</li>
4446<li>
4447
4448<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>
4449</li>
4450<li>
4451
4452<p>Arguments:</p>
4453<ul>
4454
4455<li><tt>array1</tt> : an <tt>array</tt> or <tt>multiset</tt>.</li>
4456<li><tt>array2</tt> : an <tt>array</tt> or <tt>multiset</tt>.</li>
4457<li><tt>threshold</tt> : a <tt>double</tt> that represents the similarity threshold.</li>
4458</ul>
4459</li>
4460<li>Return Value:
4461<ul>
4462
4463<li>an <tt>array</tt> with two items:
4464<ul>
4465
4466<li>The first item contains a <tt>boolean</tt> value representing whether <tt>array1</tt> and <tt>array2</tt> are similar.</li>
4467<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>
4468</ul>
4469</li>
4470<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
4471<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
4472<li><tt>missing</tt> if any element in any input array is <tt>missing</tt>,</li>
4473<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>
4474<li>a type error will be raised if:
4475<ul>
4476
4477<li>the first or second argument is any other non-array value,
4478<ul>
4479
4480<li>or, the third argument is any other non-double value.</li>
4481</ul>
4482</li>
4483</ul>
4484</li>
4485</ul>
4486</li>
4487<li>
4488
4489<p>Note: a <a href="similarity.html#UsingIndexesToSupportSimilarityQueries">keyword index</a> can be utilized for this function.</p>
4490</li>
4491<li>Example:
4492
4493<div>
4494<div>
4495<pre class="source">similarity_jaccard_check([1,5,8,9], [1,5,9,10], 0.6);
4496</pre></div></div>
4497</li>
4498<li>
4499
4500<p>The expected result is:</p>
4501
4502<div>
4503<div>
4504<pre class="source">[ false, 0.0 ]
4505</pre></div></div>
4506</li>
4507</ul><!--
4508 ! Licensed to the Apache Software Foundation (ASF) under one
4509 ! or more contributor license agreements. See the NOTICE file
4510 ! distributed with this work for additional information
4511 ! regarding copyright ownership. The ASF licenses this file
4512 ! to you under the Apache License, Version 2.0 (the
4513 ! "License"); you may not use this file except in compliance
4514 ! with the License. You may obtain a copy of the License at
4515 !
4516 ! http://www.apache.org/licenses/LICENSE-2.0
4517 !
4518 ! Unless required by applicable law or agreed to in writing,
4519 ! software distributed under the License is distributed on an
4520 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
4521 ! KIND, either express or implied. See the License for the
4522 ! specific language governing permissions and limitations
4523 ! under the License.
4524 !-->
4525</div></div>
4526<div class="section">
4527<h2><a name="Tokenizing_Functions"></a><a name="TokenizingFunctions" id="TokenizingFunctions">Tokenizing Functions</a></h2>
4528<div class="section">
4529<h3><a name="word_tokens"></a>word_tokens</h3>
4530<ul>
4531
4532<li>
4533
4534<p>Syntax:</p>
4535
4536<div>
4537<div>
4538<pre class="source">word_tokens(string)
4539</pre></div></div>
4540</li>
4541<li>
4542
4543<p>Returns an array of word tokens of <tt>string</tt> using non_alphanumeric characters as delimiters.</p>
4544</li>
4545<li>Arguments:
4546<ul>
4547
4548<li><tt>string</tt> : a <tt>string</tt> that will be tokenized.</li>
4549</ul>
4550</li>
4551<li>Return Value:
4552<ul>
4553
4554<li>an <tt>array</tt> of <tt>string</tt> word tokens,</li>
4555<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
4556<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
4557<li>any other non-string input value will cause a type error.</li>
4558</ul>
4559</li>
4560<li>
4561
4562<p>Example:</p>
4563
4564<div>
4565<div>
4566<pre class="source">word_tokens(&quot;I like the phone, awesome!&quot;);
4567</pre></div></div>
4568</li>
4569<li>
4570
4571<p>The expected result is:</p>
4572
4573<div>
4574<div>
4575<pre class="source">[ &quot;i&quot;, &quot;like&quot;, &quot;the&quot;, &quot;phone&quot;, &quot;awesome&quot; ]
4576</pre></div></div>
4577</li>
4578</ul><!--
4579 ! Licensed to the Apache Software Foundation (ASF) under one
4580 ! or more contributor license agreements. See the NOTICE file
4581 ! distributed with this work for additional information
4582 ! regarding copyright ownership. The ASF licenses this file
4583 ! to you under the Apache License, Version 2.0 (the
4584 ! "License"); you may not use this file except in compliance
4585 ! with the License. You may obtain a copy of the License at
4586 !
4587 ! http://www.apache.org/licenses/LICENSE-2.0
4588 !
4589 ! Unless required by applicable law or agreed to in writing,
4590 ! software distributed under the License is distributed on an
4591 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
4592 ! KIND, either express or implied. See the License for the
4593 ! specific language governing permissions and limitations
4594 ! under the License.
4595 !-->
4596</div></div>
4597<div class="section">
4598<h2><a name="Temporal_Functions"></a><a name="TemporalFunctions" id="TemporalFunctions">Temporal Functions</a></h2>
4599<div class="section">
4600<h3><a name="get_year.2Fget_month.2Fget_day.2Fget_hour.2Fget_minute.2Fget_second.2Fget_millisecond"></a>get_year/get_month/get_day/get_hour/get_minute/get_second/get_millisecond</h3>
4601<ul>
4602
4603<li>
4604
4605<p>Syntax:</p>
4606
4607<div>
4608<div>
4609<pre class="source">get_year/get_month/get_day/get_hour/get_minute/get_second/get_millisecond(temporal_value)
4610</pre></div></div>
4611</li>
4612<li>
4613
4614<p>Accessors for accessing fields in a temporal value</p>
4615</li>
4616<li>Arguments:
4617<ul>
4618
4619<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>
4620</ul>
4621</li>
4622<li>Return Value:
4623<ul>
4624
4625<li>an <tt>bigint</tt> value representing the field to be extracted,</li>
4626<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
4627<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
4628<li>any other non-interval input value will cause a type error.</li>
4629</ul>
4630</li>
4631<li>
4632
4633<p>Example:</p>
4634
4635<div>
4636<div>
4637<pre class="source">{
4638 &quot;year&quot;: get_year(date(&quot;2010-10-30&quot;)),
4639 &quot;month&quot;: get_month(datetime(&quot;1987-11-19T23:49:23.938&quot;)),
4640 &quot;day&quot;: get_day(date(&quot;2010-10-30&quot;)),
4641 &quot;hour&quot;: get_hour(time(&quot;12:23:34.930&quot;)),
4642 &quot;min&quot;: get_minute(duration(&quot;P3Y73M632DT49H743M3948.94S&quot;)),
4643 &quot;second&quot;: get_second(datetime(&quot;1987-11-19T23:49:23.938&quot;)),
4644 &quot;ms&quot;: get_millisecond(duration(&quot;P3Y73M632DT49H743M3948.94S&quot;))
4645};
4646</pre></div></div>
4647</li>
4648<li>
4649
4650<p>The expected result is:</p>
4651
4652<div>
4653<div>
4654<pre class="source">{ &quot;year&quot;: 2010, &quot;month&quot;: 11, &quot;day&quot;: 30, &quot;hour&quot;: 12, &quot;min&quot;: 28, &quot;second&quot;: 23, &quot;ms&quot;: 94 }
4655</pre></div></div>
4656</li>
4657</ul></div>
4658<div class="section">
4659<h3><a name="adjust_datetime_for_timezone"></a>adjust_datetime_for_timezone</h3>
4660<ul>
4661
4662<li>
4663
4664<p>Syntax:</p>
4665
4666<div>
4667<div>
4668<pre class="source">adjust_datetime_for_timezone(datetime, string)
4669</pre></div></div>
4670</li>
4671<li>
4672
4673<p>Adjusts the given datetime <tt>datetime</tt> by applying the timezone information <tt>string</tt>.</p>
4674</li>
4675<li>Arguments:
4676<ul>
4677
4678<li><tt>datetime</tt> : a <tt>datetime</tt> value to be adjusted.</li>
4679<li><tt>string</tt> : a <tt>string</tt> representing the timezone information.</li>
4680</ul>
4681</li>
4682<li>Return Value:
4683<ul>
4684
4685<li>a <tt>string</tt> value representing the new datetime after being adjusted by the timezone information,</li>
4686<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
4687<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
4688<li>a type error will be raised if:
4689<ul>
4690
4691<li>the first argument is any other non-datetime value,</li>
4692<li>or, the second argument is any other non-string value.</li>
4693</ul>
4694</li>
4695</ul>
4696</li>
4697<li>
4698
4699<p>Example:</p>
4700
4701<div>
4702<div>
4703<pre class="source">adjust_datetime_for_timezone(datetime(&quot;2008-04-26T10:10:00&quot;), &quot;+08:00&quot;);
4704</pre></div></div>
4705</li>
4706<li>
4707
4708<p>The expected result is:</p>
4709
4710<div>
4711<div>
4712<pre class="source">&quot;2008-04-26T18:10:00.000+08:00&quot;
4713</pre></div></div>
4714</li>
4715</ul></div>
4716<div class="section">
4717<h3><a name="adjust_time_for_timezone"></a>adjust_time_for_timezone</h3>
4718<ul>
4719
4720<li>
4721
4722<p>Syntax:</p>
4723
4724<div>
4725<div>
4726<pre class="source">adjust_time_for_timezone(time, string)
4727</pre></div></div>
4728</li>
4729<li>
4730
4731<p>Adjusts the given time <tt>time</tt> by applying the timezone information <tt>string</tt>.</p>
4732</li>
4733<li>Arguments:
4734<ul>
4735
4736<li><tt>time</tt> : a <tt>time</tt> value to be adjusted.</li>
4737<li><tt>string</tt> : a <tt>string</tt> representing the timezone information.</li>
4738</ul>
4739</li>
4740<li>Return Value:
4741<ul>
4742
4743<li>a <tt>string</tt> value representing the new time after being adjusted by the timezone information,</li>
4744<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
4745<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
4746<li>a type error will be raised if:
4747<ul>
4748
4749<li>the first argument is any other non-time value,</li>
4750<li>or, the second argument is any other non-string value.</li>
4751</ul>
4752</li>
4753</ul>
4754</li>
4755<li>
4756
4757<p>Example:</p>
4758
4759<div>
4760<div>
4761<pre class="source">adjust_time_for_timezone(get_time_from_datetime(datetime(&quot;2008-04-26T10:10:00&quot;)), &quot;+08:00&quot;);
4762</pre></div></div>
4763</li>
4764<li>
4765
4766<p>The expected result is:</p>
4767
4768<div>
4769<div>
4770<pre class="source">&quot;18:10:00.000+08:00&quot;
4771</pre></div></div>
4772</li>
4773</ul></div>
4774<div class="section">
4775<h3><a name="calendar_duration_from_datetime"></a>calendar_duration_from_datetime</h3>
4776<ul>
4777
4778<li>
4779
4780<p>Syntax:</p>
4781
4782<div>
4783<div>
4784<pre class="source">calendar_duration_from_datetime(datetime, duration_value)
4785</pre></div></div>
4786</li>
4787<li>
4788
4789<p>Gets a user_friendly representation of the duration <tt>duration_value</tt> based on the given datetime <tt>datetime</tt>.</p>
4790</li>
4791<li>Arguments:
4792<ul>
4793
4794<li><tt>datetime</tt> : a <tt>datetime</tt> value to be used as the reference time point.</li>
4795<li><tt>duration_value</tt> : a <tt>duration</tt> value to be converted.</li>
4796</ul>
4797</li>
4798<li>Return Value:
4799<ul>
4800
4801<li>a <tt>duration</tt> value with the duration as <tt>duration_value</tt> but with a user_friendly representation,</li>
4802<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
4803<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
4804<li>a type error will be raised if:
4805<ul>
4806
4807<li>the first argument is any other non-datetime value,</li>
4808<li>or, the second argument is any other non-duration input value.</li>
4809</ul>
4810</li>
4811</ul>
4812</li>
4813<li>
4814
4815<p>Example:</p>
4816
4817<div>
4818<div>
4819<pre class="source">calendar_duration_from_datetime(
4820 datetime(&quot;2016-03-26T10:10:00&quot;),
4821 datetime(&quot;2016-03-26T10:10:00&quot;) - datetime(&quot;2011-01-01T00:00:00&quot;)
4822);
4823</pre></div></div>
4824</li>
4825<li>
4826
4827<p>The expected result is:</p>
4828
4829<div>
4830<div>
4831<pre class="source">duration(&quot;P5Y2M24DT10H10M&quot;)
4832</pre></div></div>
4833</li>
4834</ul></div>
4835<div class="section">
4836<h3><a name="get_year_month_duration.2Fget_day_time_duration"></a>get_year_month_duration/get_day_time_duration</h3>
4837<ul>
4838
4839<li>
4840
4841<p>Syntax:</p>
4842
4843<div>
4844<div>
4845<pre class="source">get_year_month_duration/get_day_time_duration(duration_value)
4846</pre></div></div>
4847</li>
4848<li>
4849
4850<p>Extracts the correct <tt>duration</tt> subtype from <tt>duration_value</tt>.</p>
4851</li>
4852<li>Arguments:
4853<ul>
4854
4855<li><tt>duration_value</tt> : a <tt>duration</tt> value to be converted.</li>
4856</ul>
4857</li>
4858<li>Return Value:
4859<ul>
4860
4861<li>a <tt>year_month_duration</tt> value or a <tt>day_time_duration</tt> value,</li>
4862<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
4863<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
4864<li>any other non-duration input value will cause a type error.</li>
4865</ul>
4866</li>
4867<li>
4868
4869<p>Example:</p>
4870
4871<div>
4872<div>
4873<pre class="source">get_year_month_duration(duration(&quot;P12M50DT10H&quot;));
4874</pre></div></div>
4875</li>
4876<li>
4877
4878<p>The expected result is:</p>
4879
4880<div>
4881<div>
4882<pre class="source">year_month_duration(&quot;P1Y&quot;)
4883</pre></div></div>
4884</li>
4885</ul></div>
4886<div class="section">
4887<h3><a name="months_from_year_month_duration.2Fms_from_day_time_duration"></a>months_from_year_month_duration/ms_from_day_time_duration</h3>
4888<ul>
4889
4890<li>
4891
4892<p>Syntax:</p>
4893
4894<div>
4895<div>
4896<pre class="source">months_from_year_month_duration/ms_from_day_time_duration(duration_value)
4897</pre></div></div>
4898</li>
4899<li>
4900
4901<p>Extracts the number of months or the number of milliseconds from the <tt>duration</tt> subtype.</p>
4902</li>
4903<li>Arguments:
4904<ul>
4905
4906<li><tt>duration_value</tt> : a <tt>duration</tt> of the correct subtype.</li>
4907</ul>
4908</li>
4909<li>Return Value:
4910<ul>
4911
4912<li>a <tt>bigint</tt> representing the number of months/milliseconds,</li>
4913<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
4914<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
4915<li>any other non-duration input value will cause a type error.</li>
4916</ul>
4917</li>
4918<li>
4919
4920<p>Example:</p>
4921
4922<div>
4923<div>
4924<pre class="source">{
4925 &quot;months&quot;: months_from_year_month_duration(get_year_month_duration(duration(&quot;P5Y7MT50M&quot;))),
4926 &quot;milliseconds&quot;: ms_from_day_time_duration(get_day_time_duration(duration(&quot;P5Y7MT50M&quot;)))
4927};
4928</pre></div></div>
4929</li>
4930<li>
4931
4932<p>The expected result is:</p>
4933
4934<div>
4935<div>
4936<pre class="source">{&quot;months&quot;: 67, &quot;milliseconds&quot;: 3000000}
4937</pre></div></div>
4938</li>
4939</ul></div>
4940<div class="section">
4941<h3><a name="duration_from_months.2Fduration_from_ms"></a>duration_from_months/duration_from_ms</h3>
4942<ul>
4943
4944<li>
4945
4946<p>Syntax:</p>
4947
4948<div>
4949<div>
4950<pre class="source">duration_from_months/duration_from_ms(number_value)
4951</pre></div></div>
4952</li>
4953<li>
4954
4955<p>Creates a <tt>duration</tt> from <tt>number_value</tt>.</p>
4956</li>
4957<li>Arguments:
4958<ul>
4959
4960<li><tt>number_value</tt> : a <tt>bigint</tt> representing the number of months/milliseconds</li>
4961</ul>
4962</li>
4963<li>Return Value:
4964<ul>
4965
4966<li>a <tt>duration</tt> containing <tt>number_value</tt> value for months/milliseconds,</li>
4967<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
4968<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
4969<li>any other non-duration input value will cause a type error.</li>
4970</ul>
4971</li>
4972<li>
4973
4974<p>Example:</p>
4975
4976<div>
4977<div>
4978<pre class="source">duration_from_months(8);
4979</pre></div></div>
4980</li>
4981<li>
4982
4983<p>The expected result is:</p>
4984
4985<div>
4986<div>
4987<pre class="source">duration(&quot;P8M&quot;)
4988</pre></div></div>
4989</li>
4990</ul></div>
4991<div class="section">
4992<h3><a name="duration_from_interval"></a>duration_from_interval</h3>
4993<ul>
4994
4995<li>
4996
4997<p>Syntax:</p>
4998
4999<div>
5000<div>
5001<pre class="source">duration_from_interval(interval_value)
5002</pre></div></div>
5003</li>
5004<li>
5005
5006<p>Creates a <tt>duration</tt> from <tt>interval_value</tt>.</p>
5007</li>
5008<li>Arguments:
5009<ul>
5010
5011<li><tt>interval_value</tt> : an <tt>interval</tt> value</li>
5012</ul>
5013</li>
5014<li>Return Value:
5015<ul>
5016
5017<li>a <tt>duration</tt> representing the time in the <tt>interval_value</tt></li>
5018<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5019<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5020<li>any other non-duration input value will cause a type error.</li>
5021</ul>
5022</li>
5023<li>
5024
5025<p>Example:</p>
5026
5027<div>
5028<div>
5029<pre class="source">{
5030 &quot;dr1&quot; : duration_from_interval(interval(date(&quot;2010-10-30&quot;), date(&quot;2010-12-21&quot;))),
5031 &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;))),
5032 &quot;dr3&quot; : duration_from_interval(interval(time(&quot;12:32:38&quot;), time(&quot;20:29:20&quot;))),
5033 &quot;dr4&quot; : duration_from_interval(null)
5034};
5035</pre></div></div>
5036</li>
5037<li>
5038
5039<p>The expected result is:</p>
5040
5041<div>
5042<div>
5043<pre class="source">{
5044 &quot;dr1&quot;: day_time_duration(&quot;P52D&quot;),
5045 &quot;dr2&quot;: day_time_duration(&quot;P31DT1H1M1.111S&quot;),
5046 &quot;dr3&quot;: day_time_duration(&quot;PT7H56M42S&quot;),
5047 &quot;dr4&quot;: null
5048}
5049</pre></div></div>
5050</li>
5051</ul></div>
5052<div class="section">
5053<h3><a name="current_date"></a>current_date</h3>
5054<ul>
5055
5056<li>
5057
5058<p>Syntax:</p>
5059
5060<div>
5061<div>
5062<pre class="source">current_date()
5063</pre></div></div>
5064</li>
5065<li>
5066
5067<p>Gets the current date.</p>
5068</li>
5069<li>Arguments: None</li>
5070<li>Return Value:
5071<ul>
5072
5073<li>a <tt>date</tt> value of the date when the function is called.</li>
5074</ul>
5075</li>
5076</ul></div>
5077<div class="section">
5078<h3><a name="current_time"></a>current_time</h3>
5079<ul>
5080
5081<li>
5082
5083<p>Syntax:</p>
5084
5085<div>
5086<div>
5087<pre class="source">current_time()
5088</pre></div></div>
5089</li>
5090<li>
5091
5092<p>Get the current time</p>
5093</li>
5094<li>Arguments: None</li>
5095<li>Return Value:
5096<ul>
5097
5098<li>a <tt>time</tt> value of the time when the function is called.</li>
5099</ul>
5100</li>
5101</ul></div>
5102<div class="section">
5103<h3><a name="current_datetime"></a>current_datetime</h3>
5104<ul>
5105
5106<li>
5107
5108<p>Syntax:</p>
5109
5110<div>
5111<div>
5112<pre class="source">current_datetime()
5113</pre></div></div>
5114</li>
5115<li>
5116
5117<p>Get the current datetime</p>
5118</li>
5119<li>Arguments: None</li>
5120<li>Return Value:
5121<ul>
5122
5123<li>a <tt>datetime</tt> value of the datetime when the function is called.</li>
5124</ul>
5125</li>
5126</ul></div>
5127<div class="section">
5128<h3><a name="get_date_from_datetime"></a>get_date_from_datetime</h3>
5129<ul>
5130
5131<li>
5132
5133<p>Syntax:</p>
5134
5135<div>
5136<div>
5137<pre class="source">get_date_from_datetime(datetime)
5138</pre></div></div>
5139</li>
5140<li>
5141
5142<p>Gets the date value from the given datetime value <tt>datetime</tt>.</p>
5143</li>
5144<li>Arguments:
5145<ul>
5146
5147<li><tt>datetime</tt>: a <tt>datetime</tt> value to be extracted from.</li>
5148</ul>
5149</li>
5150<li>Return Value:
5151<ul>
5152
5153<li>a <tt>date</tt> value from the datetime,</li>
5154<li>any other non-datetime input value will cause a type error.</li>
5155</ul>
5156</li>
5157<li>
5158
5159<p>Example:</p>
5160<p>get_date_from_datetime(datetime(&#x201c;2016-03-26T10:10:00&#x201d;));</p>
5161</li>
5162<li>
5163
5164<p>The expected result is:</p>
5165<p>date(&#x201c;2016-03-26&#x201d;)</p>
5166</li>
5167</ul></div>
5168<div class="section">
5169<h3><a name="get_time_from_datetime"></a>get_time_from_datetime</h3>
5170<ul>
5171
5172<li>
5173
5174<p>Syntax:</p>
5175
5176<div>
5177<div>
5178<pre class="source">get_time_from_datetime(datetime)
5179</pre></div></div>
5180</li>
5181<li>
5182
5183<p>Get the time value from the given datetime value <tt>datetime</tt></p>
5184</li>
5185<li>Arguments:
5186<ul>
5187
5188<li><tt>datetime</tt>: a <tt>datetime</tt> value to be extracted from.</li>
5189</ul>
5190</li>
5191<li>Return Value:
5192<ul>
5193
5194<li>a <tt>time</tt> value from the datetime.</li>
5195<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5196<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5197<li>any other non-datetime input value will cause a type error.</li>
5198</ul>
5199</li>
5200<li>
5201
5202<p>Example:</p>
5203
5204<div>
5205<div>
5206<pre class="source">get_time_from_datetime(datetime(&quot;2016-03-26T10:10:00&quot;));
5207</pre></div></div>
5208</li>
5209<li>
5210
5211<p>The expected result is:</p>
5212
5213<div>
5214<div>
5215<pre class="source">time(&quot;10:10:00.000&quot;)
5216</pre></div></div>
5217</li>
5218</ul></div>
5219<div class="section">
5220<h3><a name="day_of_week"></a>day_of_week</h3>
5221<ul>
5222
5223<li>
5224
5225<p>Syntax:</p>
5226
5227<div>
5228<div>
5229<pre class="source">day_of_week(date[, week_start_day])
5230</pre></div></div>
5231</li>
5232<li>
5233
5234<p>Finds the day of the week for a given date (1_7)</p>
5235</li>
5236<li>Arguments:
5237<ul>
5238
5239<li><tt>date</tt>: a <tt>date</tt> or a <tt>datetime</tt> value</li>
5240<li><tt>week_start_day</tt>: (Optional) an integer or a string value (case-insensitive) specifying the day of the week to start counting from: 1=Sun[day], 2=Mon[day], &#x2026;, 7=Sat[urday]. If omitted, the default is 1 (Sunday).</li>
5241</ul>
5242</li>
5243<li>Return Value:
5244<ul>
5245
5246<li>an <tt>bigint</tt> representing the day of the week (1_7),</li>
5247<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5248<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5249<li>any other non-date input value will cause a type error.</li>
5250</ul>
5251</li>
5252<li>
5253
5254<p>Example:</p>
5255
5256<div>
5257<div>
5258<pre class="source">{
5259 &quot;day_1&quot;: day_of_week(datetime(&quot;2012-12-30T12:12:12.039&quot;)),
5260 &quot;day_2&quot;: day_of_week(datetime(&quot;2012-12-30T12:12:12.039&quot;), 2),
5261 &quot;day_3&quot;: day_of_week(datetime(&quot;2012-12-30T12:12:12.039&quot;), &quot;Monday&quot;),
5262 &quot;day_4&quot;: day_of_week(datetime(&quot;2012-12-30T12:12:12.039&quot;), &quot;MON&quot;)
5263};
5264</pre></div></div>
5265</li>
5266<li>
5267
5268<p>The expected result is:</p>
5269
5270<div>
5271<div>
5272<pre class="source">{ &quot;day_1&quot;: 1, &quot;day_2&quot;: 7, &quot;day_3&quot;: 7, &quot;day_4&quot;: 7 }
5273</pre></div></div>
5274</li>
5275</ul></div>
5276<div class="section">
5277<h3><a name="day_of_year"></a>day_of_year</h3>
5278<ul>
5279
5280<li>
5281
5282<p>Syntax:</p>
5283
5284<div>
5285<div>
5286<pre class="source">day_of_year(date)
5287</pre></div></div>
5288</li>
5289<li>
5290
5291<p>Finds the day of the year for a given date</p>
5292</li>
5293<li>Arguments:
5294<ul>
5295
5296<li><tt>date</tt>: a <tt>date</tt> or a <tt>datetime</tt> value</li>
5297</ul>
5298</li>
5299<li>Return Value:
5300<ul>
5301
5302<li>an <tt>bigint</tt> representing the day of the year,</li>
5303<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5304<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5305<li>any other non-date input value will cause a type error.</li>
5306</ul>
5307</li>
5308<li>
5309
5310<p>Example:</p>
5311
5312<div>
5313<div>
5314<pre class="source">day_of_year(date(&quot;2011-12-31&quot;));
5315</pre></div></div>
5316</li>
5317<li>
5318
5319<p>The expected result is:</p>
5320
5321<div>
5322<div>
5323<pre class="source">365
5324</pre></div></div>
5325</li>
5326</ul></div>
5327<div class="section">
5328<h3><a name="week_of_year"></a>week_of_year</h3>
5329<ul>
5330
5331<li>
5332
5333<p>Syntax:</p>
5334
5335<div>
5336<div>
5337<pre class="source">week_of_year(date[, week_start_day])
5338</pre></div></div>
5339</li>
5340<li>
5341
5342<p>Finds the week of the year for a given date</p>
5343</li>
5344<li>Arguments:
5345<ul>
5346
5347<li><tt>date</tt>: a <tt>date</tt> or a <tt>datetime</tt> value</li>
5348<li><tt>week_start_day</tt>: (Optional) an integer or a string value (case-insensitive) specifying the day of the week to start counting from: 1=Sun[day], 2=Mon[day], &#x2026;, 7=Sat[urday]. If omitted, the default is 1 (Sunday).</li>
5349</ul>
5350</li>
5351<li>Return Value:
5352<ul>
5353
5354<li>an <tt>bigint</tt> representing the week of the year,</li>
5355<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5356<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5357<li>any other non-date input value will cause a type error.</li>
5358</ul>
5359</li>
5360<li>
5361
5362<p>Example:</p>
5363
5364<div>
5365<div>
5366<pre class="source">{
5367 &quot;week_1&quot;: week_of_year(date(&quot;2012-12-01&quot;)),
5368 &quot;week_2&quot;: week_of_year(date(&quot;2012-12-01&quot;), 2),
5369 &quot;week_3&quot;: week_of_year(date(&quot;2012-12-01&quot;), &quot;Monday&quot;),
5370 &quot;week_4&quot;: week_of_year(date(&quot;2012-12-01&quot;), &quot;MON&quot;)
5371};
5372</pre></div></div>
5373</li>
5374<li>
5375
5376<p>The expected result is:</p>
5377
5378<div>
5379<div>
5380<pre class="source">{ &quot;week_1&quot;: 48, &quot;week_2&quot;: 49, &quot;week_3&quot;: 49, &quot;week_4&quot;: 49 }
5381</pre></div></div>
5382</li>
5383</ul></div>
5384<div class="section">
5385<h3><a name="quarter_of_year"></a>quarter_of_year</h3>
5386<ul>
5387
5388<li>
5389
5390<p>Syntax:</p>
5391
5392<div>
5393<div>
5394<pre class="source">quarter_of_year(date)
5395</pre></div></div>
5396</li>
5397<li>
5398
5399<p>Finds the quarter of the year for a given date</p>
5400</li>
5401<li>Arguments:
5402<ul>
5403
5404<li><tt>date</tt>: a <tt>date</tt> or a <tt>datetime</tt> value</li>
5405</ul>
5406</li>
5407<li>Return Value:
5408<ul>
5409
5410<li>an <tt>bigint</tt> representing the quarter of the year (1_4),</li>
5411<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5412<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5413<li>any other non-date input value will cause a type error.</li>
5414</ul>
5415</li>
5416<li>
5417
5418<p>Example:</p>
5419
5420<div>
5421<div>
5422<pre class="source">quarter_of_year(date(&quot;2011-12-31&quot;));
5423</pre></div></div>
5424</li>
5425<li>
5426
5427<p>The expected result is:</p>
5428
5429<div>
5430<div>
5431<pre class="source">4
5432</pre></div></div>
5433</li>
5434</ul></div>
5435<div class="section">
5436<h3><a name="datetime_from_date_time"></a>datetime_from_date_time</h3>
5437<ul>
5438
5439<li>Syntax:</li>
5440</ul>
5441<p>datetime_from_date_time(date,time)</p>
5442<ul>
5443
5444<li>Gets a datetime representing the combination of <tt>date</tt> and <tt>time</tt>
5445<ul>
5446
5447<li>Arguments:</li>
5448<li><tt>date</tt>: a <tt>date</tt> value</li>
5449<li><tt>time</tt> a <tt>time</tt> value</li>
5450</ul>
5451</li>
5452<li>Return Value:
5453<ul>
5454
5455<li>a <tt>datetime</tt> value by combining <tt>date</tt> and <tt>time</tt>,</li>
5456<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
5457<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
5458<li>a type error will be raised if
5459<ul>
5460
5461<li>the first argument is any other non-date value,</li>
5462<li>or, the second argument is any other non-time value.</li>
5463</ul>
5464</li>
5465</ul>
5466</li>
5467</ul></div>
5468<div class="section">
5469<h3><a name="date_from_unix_time_in_days"></a>date_from_unix_time_in_days</h3>
5470<ul>
5471
5472<li>
5473
5474<p>Syntax:</p>
5475
5476<div>
5477<div>
5478<pre class="source">date_from_unix_time_in_days(numeric_value)
5479</pre></div></div>
5480</li>
5481<li>
5482
5483<p>Gets a date representing the time after <tt>numeric_value</tt> days since 1970-01-01.</p>
5484</li>
5485<li>Arguments:
5486<ul>
5487
5488<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>
5489</ul>
5490</li>
5491<li>Return Value:
5492<ul>
5493
5494<li>a <tt>date</tt> value as the time after <tt>numeric_value</tt> days since 1970-01-01,</li>
5495<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5496<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5497<li>any other non-numeric input value will cause a type error.</li>
5498</ul>
5499</li>
5500<li>
5501
5502<p>Example:</p>
5503
5504<div>
5505<div>
5506<pre class="source">date_from_unix_time_in_days(15800);
5507</pre></div></div>
5508</li>
5509<li>
5510
5511<p>The expected result is:</p>
5512<p>date(&#x201c;2013-04-05&#x201d;)</p>
5513</li>
5514</ul></div>
5515<div class="section">
5516<h3><a name="datetime_from_unix_time_in_ms"></a>datetime_from_unix_time_in_ms</h3>
5517<ul>
5518
5519<li>
5520
5521<p>Syntax:</p>
5522
5523<div>
5524<div>
5525<pre class="source">datetime_from_unix_time_in_ms(numeric_value[, string])
5526</pre></div></div>
5527</li>
5528<li>
5529
5530<p>Gets a datetime representing the time after <tt>numeric_value</tt> milliseconds since 1970-01-01T00:00:00Z.</p>
5531</li>
5532<li>Arguments:
5533<ul>
5534
5535<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>
5536<li><tt>string</tt> : (Optional) a string representing the target timezone as defined by IANA Time Zone Database. If omitted, the default is UTC.</li>
5537</ul>
5538</li>
5539<li>Return Value:
5540<ul>
5541
5542<li>a <tt>datetime</tt> value as the time in the target time zone after <tt>numeric_value</tt> milliseconds since 1970-01-01T00:00:00Z,</li>
5543<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5544<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5545<li>any other non-numeric input value will cause a type error.</li>
5546</ul>
5547</li>
5548<li>
5549
5550<p>Example:</p>
5551
5552<div>
5553<div>
5554<pre class="source"> {
5555 &quot;datetime_1&quot;: datetime_from_unix_time_in_ms(1365139700000),
5556 &quot;datetime_2&quot;: datetime_from_unix_time_in_ms(1365139700000, &quot;America/Los_Angeles&quot;)
5557 };
5558</pre></div></div>
5559</li>
5560<li>
5561
5562<p>The expected result is:</p>
5563<p>{ &#x201c;datetime_1&#x201d;: datetime(&#x201c;2013-04-05T05:28:20.000&#x201d;), &#x201c;datetime_2&#x201d;: datetime(&#x201c;2013-04-04T22:28:20.000&#x201d;) }</p>
5564</li>
5565</ul></div>
5566<div class="section">
5567<h3><a name="datetime_from_unix_time_in_secs"></a>datetime_from_unix_time_in_secs</h3>
5568<ul>
5569
5570<li>
5571
5572<p>Syntax:</p>
5573
5574<div>
5575<div>
5576<pre class="source">datetime_from_unix_time_in_secs(numeric_value[, string])
5577</pre></div></div>
5578</li>
5579<li>
5580
5581<p>Gets a datetime representing the time after <tt>numeric_value</tt> seconds since 1970-01-01T00:00:00Z.</p>
5582</li>
5583<li>Arguments:
5584<ul>
5585
5586<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>
5587<li><tt>string</tt> : (Optional) a string representing the target timezone as defined by IANA Time Zone Database. If omitted, the default is UTC.</li>
5588</ul>
5589</li>
5590<li>Return Value:
5591<ul>
5592
5593<li>a <tt>datetime</tt> value as the time in the target time zone after <tt>numeric_value</tt> seconds since 1970-01-01T00:00:00Z,</li>
5594<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5595<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5596<li>any other non-numeric input value will cause a type error.</li>
5597</ul>
5598</li>
5599<li>
5600
5601<p>Example:</p>
5602
5603<div>
5604<div>
5605<pre class="source">{
5606 &quot;datetime_1&quot;: datetime_from_unix_time_in_secs(1365139700),
5607 &quot;datetime_2&quot;: datetime_from_unix_time_in_secs(1365139700, &quot;America/Los_Angeles&quot;)
5608};
5609</pre></div></div>
5610</li>
5611<li>
5612
5613<p>The expected result is:</p>
5614<p>{ &#x201c;datetime_1&#x201d;: datetime(&#x201c;2013-04-05T05:28:20.000&#x201d;), &#x201c;datetime_2&#x201d;: datetime(&#x201c;2013-04-04T22:28:20.000&#x201d;) }</p>
5615</li>
5616</ul></div>
5617<div class="section">
5618<h3><a name="time_from_unix_time_in_ms"></a>time_from_unix_time_in_ms</h3>
5619<ul>
5620
5621<li>
5622
5623<p>Syntax:</p>
5624
5625<div>
5626<div>
5627<pre class="source">time_from_unix_time_in_ms(numeric_value)
5628</pre></div></div>
5629</li>
5630<li>
5631
5632<p>Gets a time representing the time after <tt>numeric_value</tt> milliseconds since 00:00:00.000.</p>
5633</li>
5634<li>Arguments:
5635<ul>
5636
5637<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>
5638</ul>
5639</li>
5640<li>Return Value:
5641<ul>
5642
5643<li>a <tt>time</tt> value as the time after <tt>numeric_value</tt> milliseconds since 00:00:00.000,</li>
5644<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5645<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5646<li>any other non-numeric input value will cause a type error.</li>
5647</ul>
5648</li>
5649<li>
5650
5651<p>Example:</p>
5652
5653<div>
5654<div>
5655<pre class="source">time_from_unix_time_in_ms(3748);
5656</pre></div></div>
5657</li>
5658<li>
5659
5660<p>The expected result is:</p>
5661
5662<div>
5663<div>
5664<pre class="source">time(&quot;00:00:03.748&quot;)
5665</pre></div></div>
5666</li>
5667</ul></div>
5668<div class="section">
5669<h3><a name="unix_time_from_date_in_days"></a>unix_time_from_date_in_days</h3>
5670<ul>
5671
5672<li>
5673
5674<p>Syntax:</p>
5675
5676<div>
5677<div>
5678<pre class="source">unix_time_from_date_in_days(date_value)
5679</pre></div></div>
5680</li>
5681<li>
5682
5683<p>Gets an integer value representing the number of days since 1970-01-01 for <tt>date_value</tt>.</p>
5684</li>
5685<li>Arguments:
5686<ul>
5687
5688<li><tt>date_value</tt>: a <tt>date</tt> value.</li>
5689</ul>
5690</li>
5691<li>Return Value:
5692<ul>
5693
5694<li>a <tt>bigint</tt> value representing the number of days,</li>
5695<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5696<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5697<li>any other non-date input value will cause a type error.</li>
5698</ul>
5699</li>
5700<li>
5701
5702<p>Example:</p>
5703<p>unix_time_from_date_in_days(date(&#x201c;2013-04-05&#x201d;));</p>
5704</li>
5705<li>
5706
5707<p>The expected result is:</p>
5708<p>15800</p>
5709</li>
5710</ul></div>
5711<div class="section">
5712<h3><a name="unix_time_from_datetime_in_ms"></a>unix_time_from_datetime_in_ms</h3>
5713<ul>
5714
5715<li>
5716
5717<p>Syntax:</p>
5718
5719<div>
5720<div>
5721<pre class="source">unix_time_from_datetime_in_ms(datetime_value[, string])
5722</pre></div></div>
5723</li>
5724<li>
5725
5726<p>Gets an integer value representing the time in milliseconds since 1970-01-01T00:00:00Z for <tt>datetime_value</tt>.</p>
5727</li>
5728<li>Arguments:
5729<ul>
5730
5731<li><tt>datetime_value</tt> : a <tt>datetime</tt> value.</li>
5732<li><tt>string</tt> : (Optional) a string representing the source timezone as defined by IANA Time Zone Database. If omitted, the default is UTC.</li>
5733</ul>
5734</li>
5735<li>
5736
5737<p>Return Value:</p>
5738<ul>
5739
5740<li>a <tt>bigint</tt> value representing the number of milliseconds,</li>
5741<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5742<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5743<li>any other non-datetime input value will cause a type error.</li>
5744</ul>
5745</li>
5746<li>
5747
5748<p>Example:</p>
5749<p>{ &#x201c;unix_time_1&#x201d;: unix_time_from_datetime_in_ms(datetime(&#x201c;2013-04-05T05:28:20.000&#x201d;)), &#x201c;unix_time_2&#x201d;: unix_time_from_datetime_in_ms(datetime(&#x201c;2013-04-04T22:28:20.000&#x201d;), &#x201c;America/Los_Angeles&#x201d;) };</p>
5750</li>
5751<li>
5752
5753<p>The expected result is:</p>
5754<p>{ &#x201c;unix_time_1&#x201d;: 1365139700000, &#x201c;unix_time_2&#x201d;: 1365139700000 }</p>
5755</li>
5756</ul></div>
5757<div class="section">
5758<h3><a name="unix_time_from_datetime_in_secs"></a>unix_time_from_datetime_in_secs</h3>
5759<ul>
5760
5761<li>
5762
5763<p>Syntax:</p>
5764
5765<div>
5766<div>
5767<pre class="source">unix_time_from_datetime_in_secs(datetime_value[, string])
5768</pre></div></div>
5769</li>
5770<li>
5771
5772<p>Gets an integer value representing the time in seconds since 1970-01-01T00:00:00Z for <tt>datetime_value</tt>.</p>
5773</li>
5774<li>Arguments:
5775<ul>
5776
5777<li><tt>datetime_value</tt> : a <tt>datetime</tt> value.</li>
5778</ul>
5779</li>
5780<li><tt>string</tt> : (Optional) a string representing the source timezone as defined by IANA Time Zone Database. If omitted, the default is UTC.</li>
5781<li>Return Value:
5782<ul>
5783
5784<li>a <tt>bigint</tt> value representing the number of seconds,</li>
5785<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5786<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5787<li>any other non-datetime input value will cause a type error.</li>
5788</ul>
5789</li>
5790<li>
5791
5792<p>Example:</p>
5793<p>{ &#x201c;unix_time_1&#x201d;: unix_time_from_datetime_in_secs(datetime(&#x201c;2013-04-05T05:28:20.000&#x201d;)), &#x201c;unix_time_2&#x201d;: unix_time_from_datetime_in_secs(datetime(&#x201c;2013-04-04T22:28:20.000&#x201d;), &#x201c;America/Los_Angeles&#x201d;) };</p>
5794</li>
5795<li>
5796
5797<p>The expected result is:</p>
5798<p>{ &#x201c;unix_time_1&#x201d;: 1365139700, &#x201c;unix_time_2&#x201d;: 1365139700 }</p>
5799</li>
5800</ul></div>
5801<div class="section">
5802<h3><a name="unix_time_from_time_in_ms"></a>unix_time_from_time_in_ms</h3>
5803<ul>
5804
5805<li>
5806
5807<p>Syntax:</p>
5808
5809<div>
5810<div>
5811<pre class="source">unix_time_from_time_in_ms(time_value)
5812</pre></div></div>
5813</li>
5814<li>
5815
5816<p>Gets an integer value representing the time the milliseconds since 00:00:00.000 for <tt>time_value</tt>.</p>
5817</li>
5818<li>Arguments:
5819<ul>
5820
5821<li><tt>time_value</tt> : a <tt>time</tt> value.</li>
5822</ul>
5823</li>
5824<li>Return Value:
5825<ul>
5826
5827<li>a <tt>bigint</tt> value representing the number of milliseconds,</li>
5828<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
5829<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
5830<li>any other non-datetime input value will cause a type error.</li>
5831</ul>
5832</li>
5833<li>
5834
5835<p>Example:</p>
5836
5837<div>
5838<div>
5839<pre class="source">unix_time_from_time_in_ms(time(&quot;00:00:03.748&quot;));
5840</pre></div></div>
5841</li>
5842<li>
5843
5844<p>The expected result is:</p>
5845
5846<div>
5847<div>
5848<pre class="source">3748
5849</pre></div></div>
5850</li>
5851</ul></div>
5852<div class="section">
5853<h3><a name="parse_date.2Fparse_time.2Fparse_datetime"></a>parse_date/parse_time/parse_datetime</h3>
5854<ul>
5855
5856<li>Syntax:</li>
5857</ul>
5858<p>parse_date/parse_time/parse_datetime(date,formatting_expression)</p>
5859<ul>
5860
5861<li>Creates a <tt>date/time/date_time</tt> value by treating <tt>date</tt> with formatting <tt>formatting_expression</tt></li>
5862<li>Arguments:
5863<ul>
5864
5865<li><tt>date</tt>: a <tt>string</tt> value representing the <tt>date/time/datetime</tt>.</li>
5866<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>
5867<li><tt>h</tt> hours</li>
5868<li><tt>m</tt> minutes</li>
5869<li><tt>s</tt> seconds</li>
5870<li><tt>n</tt> (or <tt>S</tt>) milliseconds</li>
5871<li><tt>a</tt> am/pm</li>
5872<li><tt>z</tt> timezone (parsed and ignored)</li>
5873<li><tt>Y</tt> year</li>
5874<li><tt>Q</tt> quarter of year (1-4)</li>
5875<li><tt>QQ</tt> quarter of year (01-04)</li>
5876<li><tt>M</tt> month</li>
5877<li><tt>D</tt> day</li>
5878<li><tt>EEE</tt> weekday (abbreviated name, parsed and ignored)</li>
5879<li><tt>EEEE</tt> weekday (full name, parsed and ignored)</li>
5880<li><tt>_</tt>, <tt>'</tt>, <tt>/</tt>, <tt>.</tt>, <tt>,</tt>, <tt>T</tt> seperators for both time and date</li>
5881</ul>
5882</li>
5883<li>Return Value:
5884<ul>
5885
5886<li>a <tt>date/time/date_time</tt> value corresponding to <tt>date</tt>,</li>
5887<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
5888<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
5889<li>a type error will be raised if:</li>
5890<li>the first argument is any other non-date value,</li>
5891<li>the second argument is any other non-string value.</li>
5892</ul>
5893</li>
5894<li>
5895
5896<p>Example:</p>
5897
5898<div>
5899<div>
5900<pre class="source">parse_time(&quot;30:30&quot;,&quot;m:s&quot;);
5901</pre></div></div>
5902</li>
5903<li>
5904
5905<p>The expected result is:</p>
5906
5907<div>
5908<div>
5909<pre class="source">time(&quot;00:30:30.000&quot;)
5910</pre></div></div>
5911</li>
5912</ul></div>
5913<div class="section">
5914<h3><a name="print_date.2Fprint_time.2Fprint_datetime"></a>print_date/print_time/print_datetime</h3>
5915<ul>
5916
5917<li>
5918
5919<p>Syntax:</p>
5920
5921<div>
5922<div>
5923<pre class="source">print_date/print_time/print_datetime(date,formatting_expression)
5924</pre></div></div>
5925</li>
5926<li>
5927
5928<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>
5929</li>
5930<li>Arguments:
5931<ul>
5932
5933<li><tt>date</tt>: a <tt>date/time/datetime</tt> value.</li>
5934<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>
5935<li><tt>h</tt> hours</li>
5936<li><tt>m</tt> minutes</li>
5937<li><tt>s</tt> seconds</li>
5938<li><tt>n</tt> (or <tt>S</tt>) milliseconds</li>
5939<li><tt>a</tt> am/pm</li>
5940<li><tt>Y</tt> year</li>
5941<li><tt>Q</tt> quarter of year (1-4)</li>
5942<li><tt>QQ</tt> quarter of year (01-04)</li>
5943<li><tt>M</tt> month</li>
5944<li><tt>MMM</tt> month (abbreviated name)</li>
5945<li><tt>MMMM</tt> month (full name)</li>
5946<li><tt>D</tt> day</li>
5947<li><tt>DDD</tt> day of year</li>
5948<li><tt>EEE</tt> weekday (abbreviated name)</li>
5949<li><tt>EEEE</tt> weekday (full name)</li>
5950<li><tt>_</tt>, <tt>'</tt>, <tt>/</tt>, <tt>.</tt>, <tt>,</tt>, <tt>T</tt> seperators for both time and date</li>
5951</ul>
5952</li>
5953<li>Return Value:
5954<ul>
5955
5956<li>a <tt>string</tt> value corresponding to <tt>date</tt>,</li>
5957<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
5958<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
5959<li>a type error will be raised if:
5960<ul>
5961
5962<li>the first argument is any other non-date value,</li>
5963<li>the second argument is any other non-string value.</li>
5964</ul>
5965</li>
5966</ul>
5967</li>
5968<li>
5969
5970<p>Example:</p>
5971
5972<div>
5973<div>
5974<pre class="source">print_time(time(&quot;00:30:30.000&quot;),&quot;m:s&quot;);
5975</pre></div></div>
5976</li>
5977<li>
5978
5979<p>The expected result is:</p>
5980
5981<div>
5982<div>
5983<pre class="source">&quot;30:30&quot;
5984</pre></div></div>
5985</li>
5986</ul></div>
5987<div class="section">
5988<h3><a name="get_interval_start.2C_get_interval_end"></a>get_interval_start, get_interval_end</h3>
5989<ul>
5990
5991<li>
5992
5993<p>Syntax:</p>
5994
5995<div>
5996<div>
5997<pre class="source">get_interval_start/get_interval_end(interval)
5998</pre></div></div>
5999</li>
6000<li>
6001
6002<p>Gets the start/end of the given interval.</p>
6003</li>
6004<li>Arguments:
6005<ul>
6006
6007<li><tt>interval</tt>: the interval to be accessed.</li>
6008</ul>
6009</li>
6010<li>Return Value:
6011<ul>
6012
6013<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>
6014<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
6015<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
6016<li>any other non-interval value will cause a type error.</li>
6017</ul>
6018</li>
6019<li>
6020
6021<p>Example:</p>
6022
6023<div>
6024<div>
6025<pre class="source">{
6026 &quot;start&quot;: get_interval_start(interval_start_from_date(&quot;1984-01-01&quot;, &quot;P1Y&quot;)),
6027 &quot;end&quot;: get_interval_end(interval_start_from_date(&quot;1984-01-01&quot;, &quot;P1Y&quot;))
6028};
6029</pre></div></div>
6030</li>
6031<li>
6032
6033<p>The expected result is:</p>
6034
6035<div>
6036<div>
6037<pre class="source">{ &quot;start&quot;: date(&quot;1984-01-01&quot;), &quot;end&quot;: date(&quot;1985-01-01&quot;) }
6038</pre></div></div>
6039</li>
6040</ul></div>
6041<div class="section">
6042<h3><a name="get_interval_start_date.2Fget_interval_start_datetimeget_interval_start_time.2C_get_interval_end_date.2Fget_interval_end_datetime.2Fget_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>
6043<ul>
6044
6045<li>
6046
6047<p>Syntax:</p>
6048
6049<div>
6050<div>
6051<pre class="source">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)
6052</pre></div></div>
6053</li>
6054<li>
6055
6056<p>Gets the start/end of the given interval for the specific date/datetime/time type.</p>
6057</li>
6058<li>Arguments:
6059<ul>
6060
6061<li><tt>interval</tt>: the interval to be accessed.</li>
6062</ul>
6063</li>
6064<li>Return Value:
6065<ul>
6066
6067<li>a <tt>time</tt>, <tt>date</tt>, or <tt>datetime</tt> (depending on the function) representing the starting or ending time,</li>
6068<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
6069<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
6070<li>any other non-interval value will cause a type error.</li>
6071</ul>
6072</li>
6073<li>
6074
6075<p>Example:</p>
6076
6077<div>
6078<div>
6079<pre class="source">{
6080 &quot;start1&quot;: get_interval_start_date(interval_start_from_date(&quot;1984-01-01&quot;, &quot;P1Y&quot;)),
6081 &quot;end1&quot;: get_interval_end_date(interval_start_from_date(&quot;1984-01-01&quot;, &quot;P1Y&quot;)),
6082 &quot;start2&quot;: get_interval_start_datetime(interval_start_from_datetime(&quot;1984-01-01T08:30:00.000&quot;, &quot;P1Y1H&quot;)),
6083 &quot;end2&quot;: get_interval_end_datetime(interval_start_from_datetime(&quot;1984-01-01T08:30:00.000&quot;, &quot;P1Y1H&quot;)),
6084 &quot;start3&quot;: get_interval_start_time(interval_start_from_time(&quot;08:30:00.000&quot;, &quot;P1H&quot;)),
6085 &quot;end3&quot;: get_interval_end_time(interval_start_from_time(&quot;08:30:00.000&quot;, &quot;P1H&quot;))
6086};
6087</pre></div></div>
6088</li>
6089<li>
6090
6091<p>The expected result is:</p>
6092
6093<div>
6094<div>
6095<pre class="source">{
6096 &quot;start1&quot;: date(&quot;1984-01-01&quot;),
6097 &quot;end1&quot;: date(&quot;1985-01-01&quot;),
6098 &quot;start2&quot;: datetime(&quot;1984-01-01T08:30:00.000&quot;),
6099 &quot;end2&quot;: datetime(&quot;1985-01-01T09:30:00.000&quot;),
6100 &quot;start3&quot;: time(&quot;08:30:00.000&quot;),
6101 &quot;end3&quot;: time(&quot;09:30:00.000&quot;)
6102}
6103</pre></div></div>
6104</li>
6105</ul></div>
6106<div class="section">
6107<h3><a name="get_overlapping_interval"></a>get_overlapping_interval</h3>
6108<ul>
6109
6110<li>
6111
6112<p>Syntax:</p>
6113
6114<div>
6115<div>
6116<pre class="source">get_overlapping_interval(interval1, interval2)
6117</pre></div></div>
6118</li>
6119<li>
6120
6121<p>Gets the start/end of the given interval for the specific date/datetime/time type.</p>
6122</li>
6123<li>Arguments:
6124<ul>
6125
6126<li><tt>interval1</tt>: an <tt>interval</tt> value</li>
6127<li><tt>interval2</tt>: an <tt>interval</tt> value</li>
6128</ul>
6129</li>
6130<li>Return Value:
6131<ul>
6132
6133<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>
6134<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
6135<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6136<li>any other non-interval input value will cause a type error.</li>
6137</ul>
6138</li>
6139<li>
6140
6141<p>Example:</p>
6142
6143<div>
6144<div>
6145<pre class="source">{
6146 &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;))),
6147 &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;))),
6148 &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;))),
6149 &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;))),
6150 &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;))),
6151 &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;)))
6152};
6153</pre></div></div>
6154</li>
6155<li>
6156
6157<p>The expected result is:</p>
6158
6159<div>
6160<div>
6161<pre class="source">{
6162 &quot;overlap1&quot;: interval(time(&quot;12:23:39.000&quot;), time(&quot;18:27:19.000&quot;)),
6163 &quot;overlap2&quot;: null,
6164 &quot;overlap3&quot;: null,
6165 &quot;overlap4&quot;: interval(date(&quot;2013-01-01&quot;), date(&quot;2014-01-01&quot;)),
6166 &quot;overlap5&quot;: interval(datetime(&quot;1989-03-04T12:23:39.000&quot;), datetime(&quot;2000-10-30T18:27:19.000&quot;)),
6167 &quot;overlap6&quot;: null
6168}
6169</pre></div></div>
6170</li>
6171</ul></div>
6172<div class="section">
6173<h3><a name="interval_bin"></a>interval_bin</h3>
6174<ul>
6175
6176<li>
6177
6178<p>Syntax:</p>
6179
6180<div>
6181<div>
6182<pre class="source">interval_bin(time_to_bin, time_bin_anchor, duration_bin_size)
6183</pre></div></div>
6184</li>
6185<li>
6186
6187<p>Returns the <tt>interval</tt> value representing the bin containing the <tt>time_to_bin</tt> value.</p>
6188</li>
6189<li>Arguments:
6190<ul>
6191
6192<li><tt>time_to_bin</tt>: a date/time/datetime value representing the time to be binned.</li>
6193<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>
6194<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:
6195<ul>
6196
6197<li>datetime +|_ year_month_duration</li>
6198<li>datetime +|_ day_time_duration</li>
6199<li>date +|_ year_month_duration</li>
6200<li>date +|_ day_time_duration</li>
6201<li>time +|_ day_time_duration</li>
6202</ul>
6203</li>
6204</ul>
6205</li>
6206<li>Return Value:</li>
6207<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>
6208<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
6209<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6210<li>a type error will be raised if:
6211<ul>
6212
6213<li>the first argument or the second argument is any other non-date/non-time/non-datetime value,</li>
6214<li>or, the second argument is any other non-year_month_duration/non-day_time_duration value.</li>
6215</ul>
6216</li>
6217<li>
6218
6219<p>Example:</p>
6220<p>{ &#x201c;bin1&#x201d;: interval_bin(date(&#x201c;2010-10-30&#x201d;), date(&#x201c;1990-01-01&#x201d;), year_month_duration(&#x201c;P1Y&#x201d;)), &#x201c;bin2&#x201d;: interval_bin(datetime(&#x201c;1987-11-19T23:49:23.938&#x201d;), datetime(&#x201c;1990-01-01T00:00:00.000&#x201d;), year_month_duration(&#x201c;P6M&#x201d;)), &#x201c;bin3&#x201d;: interval_bin(time(&#x201c;12:23:34.930+07:00&#x201d;), time(&#x201c;00:00:00&#x201d;), day_time_duration(&#x201c;PT1M&#x201d;)), &#x201c;bin4&#x201d;: interval_bin(datetime(&#x201c;1987-11-19T23:49:23.938&#x201d;), datetime(&#x201c;2013-01-01T00:00:00.000&#x201d;), day_time_duration(&#x201c;PT24H&#x201d;)) };</p>
6221</li>
6222<li>
6223
6224<p>The expected result is:</p>
6225<p>{ &#x201c;bin1&#x201d;: interval(date(&#x201c;2010-01-01&#x201d;), date(&#x201c;2011-01-01&#x201d;)), &#x201c;bin2&#x201d;: interval(datetime(&#x201c;1987-07-01T00:00:00.000&#x201d;), datetime(&#x201c;1988-01-01T00:00:00.000&#x201d;)), &#x201c;bin3&#x201d;: interval(time(&#x201c;12:23:00.000&#x201d;), time(&#x201c;12:24:00.000&#x201d;)), &#x201c;bin4&#x201d;: interval(datetime(&#x201c;1987-11-19T00:00:00.000&#x201d;), datetime(&#x201c;1987-11-20T00:00:00.000&#x201d;)) }</p>
6226</li>
6227</ul></div>
6228<div class="section">
6229<h3><a name="interval_start_from_date.2Ftime.2Fdatetime"></a>interval_start_from_date/time/datetime</h3>
6230<ul>
6231
6232<li>
6233
6234<p>Syntax:</p>
6235
6236<div>
6237<div>
6238<pre class="source">interval_start_from_date/time/datetime(date/time/datetime, duration)
6239</pre></div></div>
6240</li>
6241<li>
6242
6243<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>
6244</li>
6245<li>Arguments:
6246<ul>
6247
6248<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>
6249<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>
6250</ul>
6251</li>
6252<li>Return Value:
6253<ul>
6254
6255<li>an <tt>interval</tt> value representing the interval starting from the given time point with the length of duration,</li>
6256<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
6257<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6258<li>a type error will be raised if:
6259<ul>
6260
6261<li>the first argument or the second argument is any other non-date/non-time/non-datetime value,</li>
6262<li>or, the second argument is any other non-duration value.</li>
6263</ul>
6264</li>
6265</ul>
6266</li>
6267<li>
6268
6269<p>Example:</p>
6270
6271<div>
6272<div>
6273<pre class="source">{
6274 &quot;interval1&quot;: interval_start_from_date(&quot;1984-01-01&quot;, &quot;P1Y&quot;),
6275 &quot;interval2&quot;: interval_start_from_time(time(&quot;02:23:28.394&quot;), &quot;PT3H24M&quot;),
6276 &quot;interval3&quot;: interval_start_from_datetime(&quot;1999-09-09T09:09:09.999&quot;, duration(&quot;P2M30D&quot;))
6277};
6278</pre></div></div>
6279</li>
6280<li>
6281
6282<p>The expected result is:</p>
6283
6284<div>
6285<div>
6286<pre class="source">{
6287 &quot;interval1&quot;: interval(date(&quot;1984-01-01&quot;), date(&quot;1985-01-01&quot;)),
6288 &quot;interval2&quot;: interval(time(&quot;02:23:28.394&quot;), time(&quot;05:47:28.394&quot;)),
6289 &quot;interval3&quot;: interval(datetime(&quot;1999-09-09T09:09:09.999&quot;), datetime(&quot;1999-12-09T09:09:09.999&quot;))
6290}
6291</pre></div></div>
6292</li>
6293</ul></div>
6294<div class="section">
6295<h3><a name="overlap_bins"></a>overlap_bins</h3>
6296<ul>
6297
6298<li>
6299
6300<p>Return Value:</p>
6301<ul>
6302
6303<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>
6304</ul>
6305</li>
6306<li>
6307
6308<p>Syntax:</p>
6309
6310<div>
6311<div>
6312<pre class="source"> overlap_bins(interval, time_bin_anchor, duration_bin_size)
6313</pre></div></div>
6314</li>
6315<li>
6316
6317<p>Returns an ordered list of <tt>interval</tt> values representing each bin that is overlapping the <tt>interval</tt>.</p>
6318</li>
6319<li>Arguments:
6320<ul>
6321
6322<li><tt>interval</tt>: an <tt>interval</tt> value</li>
6323<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>
6324<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:
6325<ul>
6326
6327<li>datetime +|_ year_month_duration</li>
6328<li>datetime +|_ day_time_duration</li>
6329<li>date +|_ year_month_duration</li>
6330<li>date +|_ day_time_duration</li>
6331<li>time +|_ day_time_duration</li>
6332</ul>
6333</li>
6334</ul>
6335</li>
6336<li>Return Value:
6337<ul>
6338
6339<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>
6340<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
6341<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6342<li>a type error will be raised if:
6343<ul>
6344
6345<li>the first arugment is any other non-interval value,</li>
6346<li>or, the second argument is any other non-date/non-time/non-datetime value,</li>
6347<li>or, the second argument is any other non-year_month_duration/non-day_time_duration value.</li>
6348</ul>
6349</li>
6350</ul>
6351</li>
6352<li>
6353
6354<p>Example:</p>
6355
6356<div>
6357<div>
6358<pre class="source">{
6359 &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;)),
6360 &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;)),
6361 &quot;datetimebins&quot;: overlap_bins(interval(datetime(&quot;1800-01-01T23:59:48.938&quot;), datetime(&quot;2015-07-26T13:28:30.218&quot;)),
6362 datetime(&quot;1900-01-01T00:00:00.000&quot;), year_month_duration(&quot;P100Y&quot;))
6363};
6364</pre></div></div>
6365</li>
6366<li>
6367
6368<p>The expected result is:</p>
6369<p>{ &#x201c;timebins&#x201d;: [ interval(time(&#x201c;17:00:00.000&#x201d;), time(&#x201c;17:30:00.000&#x201d;)), interval(time(&#x201c;17:30:00.000&#x201d;), time(&#x201c;18:00:00.000&#x201d;)), interval(time(&#x201c;18:00:00.000&#x201d;), time(&#x201c;18:30:00.000&#x201d;)), interval(time(&#x201c;18:30:00.000&#x201d;), time(&#x201c;19:00:00.000&#x201d;)) ], &#x201c;datebins&#x201d;: [ interval(date(&#x201c;1980-01-01&#x201d;), date(&#x201c;1990-01-01&#x201d;)), interval(date(&#x201c;1990-01-01&#x201d;), date(&#x201c;2000-01-01&#x201d;)), interval(date(&#x201c;2000-01-01&#x201d;), date(&#x201c;2010-01-01&#x201d;)), interval(date(&#x201c;2010-01-01&#x201d;), date(&#x201c;2020-01-01&#x201d;)) ], &#x201c;datetimebins&#x201d;: [ interval(datetime(&#x201c;1800-01-01T00:00:00.000&#x201d;), datetime(&#x201c;1900-01-01T00:00:00.000&#x201d;)), interval(datetime(&#x201c;1900-01-01T00:00:00.000&#x201d;), datetime(&#x201c;2000-01-01T00:00:00.000&#x201d;)), interval(datetime(&#x201c;2000-01-01T00:00:00.000&#x201d;), datetime(&#x201c;2100-01-01T00:00:00.000&#x201d;)) ] };</p>
6370</li>
6371</ul><!--
6372 ! Licensed to the Apache Software Foundation (ASF) under one
6373 ! or more contributor license agreements. See the NOTICE file
6374 ! distributed with this work for additional information
6375 ! regarding copyright ownership. The ASF licenses this file
6376 ! to you under the Apache License, Version 2.0 (the
6377 ! "License"); you may not use this file except in compliance
6378 ! with the License. You may obtain a copy of the License at
6379 !
6380 ! http://www.apache.org/licenses/LICENSE-2.0
6381 !
6382 ! Unless required by applicable law or agreed to in writing,
6383 ! software distributed under the License is distributed on an
6384 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
6385 ! KIND, either express or implied. See the License for the
6386 ! specific language governing permissions and limitations
6387 ! under the License.
6388 !-->
6389</div>
6390<div class="section">
6391<h3><a name="interval_before.2C_interval_after"></a>interval_before, interval_after</h3>
6392<ul>
6393
6394<li>
6395
6396<p>Syntax:</p>
6397
6398<div>
6399<div>
6400<pre class="source">interval_before(interval1, interval2)
6401interval_after(interval1, interval2)
6402</pre></div></div>
6403</li>
6404<li>
6405
6406<p>These two functions check whether an interval happens before/after another interval.</p>
6407</li>
6408<li>Arguments:
6409<ul>
6410
6411<li><tt>interval1</tt>, <tt>interval2</tt>: two intervals to be compared</li>
6412</ul>
6413</li>
6414<li>Return Value:
6415<ul>
6416
6417<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>
6418<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
6419<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6420<li>any other non-interval input value will cause a type error.</li>
6421</ul>
6422</li>
6423<li>
6424
6425<p>Examples:</p>
6426
6427<div>
6428<div>
6429<pre class="source">{
6430 &quot;interval_before&quot;: interval_before(interval(date(&quot;2000-01-01&quot;), date(&quot;2005-01-01&quot;)),
6431 interval(date(&quot;2005-05-01&quot;), date(&quot;2012-09-09&quot;))),
6432 &quot;interval_after&quot;: interval_after(interval(date(&quot;2005-05-01&quot;), date(&quot;2012-09-09&quot;)),
6433 interval(date(&quot;2000-01-01&quot;), date(&quot;2005-01-01&quot;)))
6434};
6435</pre></div></div>
6436</li>
6437<li>
6438
6439<p>The expected result is:</p>
6440
6441<div>
6442<div>
6443<pre class="source">{ &quot;interval_before&quot;: true, &quot;interval_after&quot;: true }
6444</pre></div></div>
6445</li>
6446</ul></div>
6447<div class="section">
6448<h3><a name="interval_covers.2C_interval_covered_by"></a>interval_covers, interval_covered_by</h3>
6449<ul>
6450
6451<li>
6452
6453<p>Syntax:</p>
6454
6455<div>
6456<div>
6457<pre class="source">interval_covers(interval1, interval2)
6458interval_covered_by(interval1, interval2)
6459</pre></div></div>
6460</li>
6461<li>
6462
6463<p>These two functions check whether one interval covers the other interval.</p>
6464</li>
6465<li>Arguments:
6466<ul>
6467
6468<li><tt>interval1</tt>, <tt>interval2</tt>: two intervals to be compared</li>
6469</ul>
6470</li>
6471<li>Return Value:
6472<ul>
6473
6474<li>
6475
6476<p>a <tt>boolean</tt> value. Specifically, <tt>interval_covers(interval1, interval2)</tt> is true if and only if</p>
6477<p>interval1.start &lt;= interval2.start AND interval1.end &gt;= interval2.end</p>
6478<p><tt>interval_covered_by(interval1, interval2)</tt> is true if and only if</p>
6479<p>interval2.start &lt;= interval1.start AND interval2.end &gt;= interval1.end</p>
6480</li>
6481<li>
6482
6483<p><tt>missing</tt> if the argument is a <tt>missing</tt> value,</p>
6484</li>
6485<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6486<li>any other non-interval input value will cause a type error.</li>
6487</ul>
6488</li>
6489<li>
6490
6491<p>Examples:</p>
6492
6493<div>
6494<div>
6495<pre class="source">{
6496 &quot;interval_covers&quot;: interval_covers(interval(date(&quot;2000-01-01&quot;), date(&quot;2005-01-01&quot;)),
6497 interval(date(&quot;2000-03-01&quot;), date(&quot;2004-09-09&quot;))),
6498 &quot;interval_covered_by&quot;: interval_covered_by(interval(date(&quot;2006-08-01&quot;), date(&quot;2007-03-01&quot;)),
6499 interval(date(&quot;2004-09-10&quot;), date(&quot;2012-08-01&quot;)))
6500};
6501</pre></div></div>
6502</li>
6503<li>
6504
6505<p>The expected result is:</p>
6506
6507<div>
6508<div>
6509<pre class="source">{ &quot;interval_covers&quot;: true, &quot;interval_covered_by&quot;: true }
6510</pre></div></div>
6511</li>
6512</ul></div>
6513<div class="section">
6514<h3><a name="interval_overlaps.2C_interval_overlapped_by"></a>interval_overlaps, interval_overlapped_by</h3>
6515<ul>
6516
6517<li>
6518
6519<p>Syntax:</p>
6520
6521<div>
6522<div>
6523<pre class="source">interval_overlaps(interval1, interval2)
6524interval_overlapped_by(interval1, interval2)
6525</pre></div></div>
6526</li>
6527<li>
6528
6529<p>These functions check whether two intervals overlap with each other.</p>
6530</li>
6531<li>Arguments:
6532<ul>
6533
6534<li><tt>interval1</tt>, <tt>interval2</tt>: two intervals to be compared</li>
6535</ul>
6536</li>
6537<li>Return Value:
6538<ul>
6539
6540<li>a <tt>boolean</tt> value. Specifically, <tt>interval_overlaps(interval1, interval2)</tt> is true if and only if
6541<p>interval1.start &lt; interval2.start AND interval2.end &gt; interval1.end AND interval1.end &gt; interval2.start</p></li>
6542</ul>
6543<p><tt>interval_overlapped_by(interval1, interval2)</tt> is true if and only if</p>
6544
6545<div>
6546<div>
6547<pre class="source">interval2.start &lt; interval1.start
6548AND interval1.end &gt; interval2.end
6549AND interval2.end &gt; interval1.start
6550</pre></div></div>
6551
6552<ul>
6553
6554<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
6555<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6556<li>any other non-interval input value will cause a type error.</li>
6557</ul>
6558<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>
6559</li>
6560<li>
6561
6562<p>Examples:</p>
6563
6564<div>
6565<div>
6566<pre class="source">{
6567 &quot;overlaps&quot;: interval_overlaps(interval(date(&quot;2000-01-01&quot;), date(&quot;2005-01-01&quot;)),
6568 interval(date(&quot;2004-05-01&quot;), date(&quot;2012-09-09&quot;))),
6569 &quot;overlapped_by&quot;: interval_overlapped_by(interval(date(&quot;2006-08-01&quot;), date(&quot;2007-03-01&quot;)),
6570 interval(date(&quot;2004-05-01&quot;), date(&quot;2012-09-09&quot;))))
6571};
6572</pre></div></div>
6573</li>
6574<li>
6575
6576<p>The expected result is:</p>
6577
6578<div>
6579<div>
6580<pre class="source">{ &quot;overlaps&quot;: true, &quot;overlapped_by&quot;: true }
6581</pre></div></div>
6582</li>
6583</ul></div>
6584<div class="section">
6585<h3><a name="interval_overlapping"></a>interval_overlapping</h3>
6586<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>
6587<ul>
6588
6589<li>
6590
6591<p>Syntax:</p>
6592
6593<div>
6594<div>
6595<pre class="source">interval_overlapping(interval1, interval2)
6596</pre></div></div>
6597</li>
6598<li>
6599
6600<p>This functions check whether two intervals share any points with each other.</p>
6601</li>
6602<li>Arguments:
6603<ul>
6604
6605<li><tt>interval1</tt>, <tt>interval2</tt>: two intervals to be compared</li>
6606</ul>
6607</li>
6608<li>Return Value:
6609<ul>
6610
6611<li>
6612
6613<p>a <tt>boolean</tt> value. Specifically, <tt>interval_overlapping(interval1, interval2)</tt> is true if</p>
6614<p>interval1.start &lt; interval2.end AND interval1.end &gt; interval2.start</p>
6615</li>
6616<li>
6617
6618<p><tt>missing</tt> if the argument is a <tt>missing</tt> value,</p>
6619</li>
6620<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6621<li>any other non-interval input value will cause a type error.</li>
6622</ul>
6623</li>
6624<li>
6625
6626<p>Examples:</p>
6627
6628<div>
6629<div>
6630<pre class="source">{
6631 &quot;overlapping1&quot;: interval_overlapping(interval(date(&quot;2000-01-01&quot;), date(&quot;2005-01-01&quot;)),
6632 interval(date(&quot;2004-05-01&quot;), date(&quot;2012-09-09&quot;))),
6633 &quot;overlapping2&quot;: interval_overlapping(interval(date(&quot;2006-08-01&quot;), date(&quot;2007-03-01&quot;)),
6634 interval(date(&quot;2004-09-10&quot;), date(&quot;2006-12-31&quot;)))
6635};
6636</pre></div></div>
6637</li>
6638<li>
6639
6640<p>The expected result is:</p>
6641
6642<div>
6643<div>
6644<pre class="source">{ &quot;overlapping1&quot;: true, &quot;overlapping2&quot;: true }
6645</pre></div></div>
6646</li>
6647</ul></div>
6648<div class="section">
6649<h3><a name="interval_meets.2C_interval_met_by"></a>interval_meets, interval_met_by</h3>
6650<ul>
6651
6652<li>
6653
6654<p>Syntax:</p>
6655
6656<div>
6657<div>
6658<pre class="source">interval_meets(interval1, interval2)
6659interval_met_by(interval1, interval2)
6660</pre></div></div>
6661</li>
6662<li>
6663
6664<p>These two functions check whether an interval meets with another interval.</p>
6665</li>
6666<li>Arguments:
6667<ul>
6668
6669<li><tt>interval1</tt>, <tt>interval2</tt>: two intervals to be compared</li>
6670</ul>
6671</li>
6672<li>Return Value:
6673<ul>
6674
6675<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>
6676<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
6677<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6678<li>any other non-interval input value will cause a type error.</li>
6679</ul>
6680</li>
6681<li>
6682
6683<p>Examples:</p>
6684
6685<div>
6686<div>
6687<pre class="source">{
6688 &quot;meets&quot;: interval_meets(interval(date(&quot;2000-01-01&quot;), date(&quot;2005-01-01&quot;)),
6689 interval(date(&quot;2005-01-01&quot;), date(&quot;2012-09-09&quot;))),
6690 &quot;metby&quot;: interval_met_by(interval(date(&quot;2006-08-01&quot;), date(&quot;2007-03-01&quot;)),
6691 interval(date(&quot;2004-09-10&quot;), date(&quot;2006-08-01&quot;)))
6692};
6693</pre></div></div>
6694</li>
6695<li>
6696
6697<p>The expected result is:</p>
6698
6699<div>
6700<div>
6701<pre class="source">{ &quot;meets&quot;: true, &quot;metby&quot;: true }
6702</pre></div></div>
6703</li>
6704</ul></div>
6705<div class="section">
6706<h3><a name="interval_starts.2C_interval_started_by"></a>interval_starts, interval_started_by</h3>
6707<ul>
6708
6709<li>
6710
6711<p>Syntax:</p>
6712
6713<div>
6714<div>
6715<pre class="source">interval_starts(interval1, interval2)
6716interval_started_by(interval1, interval2)
6717</pre></div></div>
6718</li>
6719<li>
6720
6721<p>These two functions check whether one interval starts with the other interval.</p>
6722</li>
6723<li>Arguments:
6724<ul>
6725
6726<li><tt>interval1</tt>, <tt>interval2</tt>: two intervals to be compared</li>
6727</ul>
6728</li>
6729<li>Return Value:
6730<ul>
6731
6732<li>a <tt>boolean</tt> value. Specifically, <tt>interval_starts(interval1, interval2)</tt> returns true if and only if
6733<p>interval1.start = interval2.start AND interval1.end &lt;= interval2.end</p></li>
6734</ul>
6735<p><tt>interval_started_by(interval1, interval2)</tt> returns true if and only if</p>
6736
6737<div>
6738<div>
6739<pre class="source">interval1.start = interval2.start
6740AND interval2.end &lt;= interval1.end
6741</pre></div></div>
6742
6743<ul>
6744
6745<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
6746<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6747<li>any other non-interval input value will cause a type error.</li>
6748</ul>
6749</li>
6750<li>
6751
6752<p>Examples:</p>
6753
6754<div>
6755<div>
6756<pre class="source">{
6757 &quot;interval_starts&quot;: interval_starts(interval(date(&quot;2000-01-01&quot;), date(&quot;2005-01-01&quot;)),
6758 interval(date(&quot;2000-01-01&quot;), date(&quot;2012-09-09&quot;))),
6759 &quot;interval_started_by&quot;: interval_started_by(interval(date(&quot;2006-08-01&quot;), date(&quot;2007-03-01&quot;)),
6760 interval(date(&quot;2006-08-01&quot;), date(&quot;2006-08-02&quot;)))
6761};
6762</pre></div></div>
6763</li>
6764<li>
6765
6766<p>The expected result is:</p>
6767
6768<div>
6769<div>
6770<pre class="source">{ &quot;interval_starts&quot;: true, &quot;interval_started_by&quot;: true }
6771</pre></div></div>
6772</li>
6773</ul></div>
6774<div class="section">
6775<h3><a name="interval_ends.2C_interval_ended_by"></a>interval_ends, interval_ended_by</h3>
6776<ul>
6777
6778<li>
6779
6780<p>Syntax:</p>
6781
6782<div>
6783<div>
6784<pre class="source">interval_ends(interval1, interval2)
6785interval_ended_by(interval1, interval2)
6786</pre></div></div>
6787</li>
6788<li>
6789
6790<p>These two functions check whether one interval ends with the other interval.</p>
6791</li>
6792<li>Arguments:
6793<ul>
6794
6795<li><tt>interval1</tt>, <tt>interval2</tt>: two intervals to be compared</li>
6796</ul>
6797</li>
6798<li>Return Value:
6799<ul>
6800
6801<li>
6802
6803<p>a <tt>boolean</tt> value. Specifically, <tt>interval_ends(interval1, interval2)</tt> returns true if and only if</p>
6804<p>interval1.end = interval2.end AND interval1.start &gt;= interval2.start</p>
6805<p><tt>interval_ended_by(interval1, interval2)</tt> returns true if and only if</p>
6806<p>interval2.end = interval1.end AND interval2.start &gt;= interval1.start</p>
6807</li>
6808<li>
6809
6810<p><tt>missing</tt> if the argument is a <tt>missing</tt> value,</p>
6811</li>
6812<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6813<li>any other non-interval input value will cause a type error.</li>
6814</ul>
6815</li>
6816<li>
6817
6818<p>Examples:</p>
6819
6820<div>
6821<div>
6822<pre class="source">{
6823 &quot;interval_ends&quot;: interval_ends(interval(date(&quot;2000-01-01&quot;), date(&quot;2005-01-01&quot;)),
6824 interval(date(&quot;1998-01-01&quot;), date(&quot;2005-01-01&quot;))),
6825 &quot;interval_ended_by&quot;: interval_ended_by(interval(date(&quot;2006-08-01&quot;), date(&quot;2007-03-01&quot;)),
6826 interval(date(&quot;2006-09-10&quot;), date(&quot;2007-03-01&quot;)))
6827};
6828</pre></div></div>
6829</li>
6830<li>
6831
6832<p>The expected result is:</p>
6833
6834<div>
6835<div>
6836<pre class="source">{ &quot;interval_ends&quot;: true, &quot;interval_ended_by&quot;: true }
6837</pre></div></div>
6838</li>
6839</ul><!--
6840 ! Licensed to the Apache Software Foundation (ASF) under one
6841 ! or more contributor license agreements. See the NOTICE file
6842 ! distributed with this work for additional information
6843 ! regarding copyright ownership. The ASF licenses this file
6844 ! to you under the Apache License, Version 2.0 (the
6845 ! "License"); you may not use this file except in compliance
6846 ! with the License. You may obtain a copy of the License at
6847 !
6848 ! http://www.apache.org/licenses/LICENSE-2.0
6849 !
6850 ! Unless required by applicable law or agreed to in writing,
6851 ! software distributed under the License is distributed on an
6852 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
6853 ! KIND, either express or implied. See the License for the
6854 ! specific language governing permissions and limitations
6855 ! under the License.
6856 !-->
6857</div></div>
6858<div class="section">
6859<h2><a name="Object_Functions"></a><a name="ObjectFunctions" id="ObjectFunctions">Object Functions</a></h2>
6860<div class="section">
6861<h3><a name="get_object_fields"></a>get_object_fields</h3>
6862<ul>
6863
6864<li>
6865
6866<p>Syntax:</p>
6867
6868<div>
6869<div>
6870<pre class="source">get_object_fields(input_object)
6871</pre></div></div>
6872</li>
6873<li>
6874
6875<p>Access the object field names, type and open status for a given object.</p>
6876</li>
6877<li>Arguments:
6878<ul>
6879
6880<li><tt>input_object</tt> : a object value.</li>
6881</ul>
6882</li>
6883<li>Return Value:
6884<ul>
6885
6886<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>
6887<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
6888<li><tt>null</tt> if the argument is a <tt>null</tt> value,</li>
6889<li>any other non-object input value will cause a type error.</li>
6890</ul>
6891</li>
6892<li>
6893
6894<p>Example:</p>
6895
6896<div>
6897<div>
6898<pre class="source">get_object_fields(
6899 {
6900 &quot;id&quot;: 1,
6901 &quot;project&quot;: &quot;AsterixDB&quot;,
6902 &quot;address&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;},
6903 &quot;related&quot;: [&quot;Hivestrix&quot;, &quot;Preglix&quot;, &quot;Apache VXQuery&quot;]
6904 }
6905 );
6906</pre></div></div>
6907</li>
6908<li>
6909
6910<p>The expected result is:</p>
6911
6912<div>
6913<div>
6914<pre class="source">[
6915 { &quot;field-name&quot;: &quot;id&quot;, &quot;field-type&quot;: &quot;INT64&quot;, &quot;is-open&quot;: false },
6916 { &quot;field-name&quot;: &quot;project&quot;, &quot;field-type&quot;: &quot;STRING&quot;, &quot;is-open&quot;: false },
6917 { &quot;field-name&quot;: &quot;address&quot;, &quot;field-type&quot;: &quot;RECORD&quot;, &quot;is-open&quot;: false,
6918 &quot;nested&quot;: [
6919 { &quot;field-name&quot;: &quot;city&quot;, &quot;field-type&quot;: &quot;STRING&quot;, &quot;is-open&quot;: false },
6920 { &quot;field-name&quot;: &quot;state&quot;, &quot;field-type&quot;: &quot;STRING&quot;, &quot;is-open&quot;: false }
6921 ]
6922 },
6923 { &quot;field-name&quot;:
6924 &quot;related&quot;,
6925 &quot;field-type&quot;: &quot;ORDEREDLIST&quot;,
6926 &quot;is-open&quot;: false,
6927 &quot;list&quot;: [
6928 { &quot;field-type&quot;: &quot;STRING&quot; },
6929 { &quot;field-type&quot;: &quot;STRING&quot; },
6930 { &quot;field-type&quot;: &quot;STRING&quot; }
6931 ]
6932 }
6933]
6934</pre></div></div>
6935</li>
6936</ul>
6937<p>]</p></div>
6938<div class="section">
6939<h3><a name="get_object_field_value"></a>get_object_field_value</h3>
6940<ul>
6941
6942<li>
6943
6944<p>Syntax:</p>
6945
6946<div>
6947<div>
6948<pre class="source">get_object_field_value(input_object, string)
6949</pre></div></div>
6950</li>
6951<li>
6952
6953<p>Access the field name given in the <tt>string_expression</tt> from the <tt>object_expression</tt>.</p>
6954</li>
6955<li>Arguments:
6956<ul>
6957
6958<li><tt>input_object</tt> : a <tt>object</tt> value.</li>
6959<li><tt>string</tt> : a <tt>string</tt> representing the top level field name.</li>
6960</ul>
6961</li>
6962<li>Return Value:
6963<ul>
6964
6965<li>an <tt>any</tt> value saved in the designated field of the object,</li>
6966<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
6967<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
6968<li>a type error will be raised if:
6969<ul>
6970
6971<li>the first argument is any other non-object value,</li>
6972<li>or, the second argument is any other non-string value.</li>
6973</ul>
6974</li>
6975</ul>
6976</li>
6977<li>
6978
6979<p>Example:</p>
6980
6981<div>
6982<div>
6983<pre class="source">get_object_field_value({
6984 &quot;id&quot;: 1,
6985 &quot;project&quot;: &quot;AsterixDB&quot;,
6986 &quot;address&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;},
6987 &quot;related&quot;: [&quot;Hivestrix&quot;, &quot;Preglix&quot;, &quot;Apache VXQuery&quot;]
6988 },
6989 &quot;project&quot;
6990 );
6991</pre></div></div>
6992</li>
6993<li>
6994
6995<p>The expected result is:</p>
6996
6997<div>
6998<div>
6999<pre class="source">&quot;AsterixDB&quot;
7000</pre></div></div>
7001</li>
7002</ul></div>
7003<div class="section">
7004<h3><a name="object_remove_fields"></a>object_remove_fields</h3>
7005<ul>
7006
7007<li>
7008
7009<p>Syntax:</p>
7010
7011<div>
7012<div>
7013<pre class="source">object_remove_fields(input_object, field_names)
7014</pre></div></div>
7015</li>
7016<li>
7017
7018<p>Remove indicated fields from a object given a list of field names.</p>
7019</li>
7020<li>Arguments:
7021<ul>
7022
7023<li><tt>input_object</tt>: a object value.</li>
7024<li><tt>field_names</tt>: an array of strings and/or array of array of strings.</li>
7025</ul>
7026</li>
7027<li>
7028
7029<p>Return Value:</p>
7030<ul>
7031
7032<li>a new object value without the fields listed in the second argument,</li>
7033<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
7034<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
7035<li>a type error will be raised if:
7036<ul>
7037
7038<li>the first argument is any other non-object value,</li>
7039<li>or, the second argument is any other non-array value or recursively contains non-string items.</li>
7040</ul>
7041</li>
7042</ul>
7043</li>
7044<li>
7045
7046<p>Example:</p>
7047
7048<div>
7049<div>
7050<pre class="source">object_remove_fields(
7051 {
7052 &quot;id&quot;:1,
7053 &quot;project&quot;:&quot;AsterixDB&quot;,
7054 &quot;address&quot;:{&quot;city&quot;:&quot;Irvine&quot;, &quot;state&quot;:&quot;CA&quot;},
7055 &quot;related&quot;:[&quot;Hivestrix&quot;, &quot;Preglix&quot;, &quot;Apache VXQuery&quot;]
7056 },
7057 [[&quot;address&quot;, &quot;city&quot;], &quot;related&quot;]
7058 );
7059</pre></div></div>
7060</li>
7061<li>
7062
7063<p>The expected result is:</p>
7064
7065<div>
7066<div>
7067<pre class="source">{
7068 &quot;id&quot;:1,
7069 &quot;project&quot;:&quot;AsterixDB&quot;,
7070 &quot;address&quot;:{ &quot;state&quot;: &quot;CA&quot; }
7071}
7072</pre></div></div>
7073</li>
7074</ul></div>
7075<div class="section">
7076<h3><a name="object_add_fields"></a>object_add_fields</h3>
7077<ul>
7078
7079<li>
7080
7081<p>Syntax:</p>
7082
7083<div>
7084<div>
7085<pre class="source">object_add_fields(input_object, fields)
7086</pre></div></div>
7087</li>
7088<li>
7089
7090<p>Add fields to a object given a list of field names.</p>
7091</li>
7092<li>Arguments:
7093<ul>
7094
7095<li><tt>input_object</tt> : a object value.</li>
7096<li><tt>fields</tt>: an array of field descriptor objects where each object has field_name and field_value.</li>
7097</ul>
7098</li>
7099<li>Return Value:
7100<ul>
7101
7102<li>a new object value with the new fields included,</li>
7103<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
7104<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
7105<li>a type error will be raised if:
7106<ul>
7107
7108<li>the first argument is any other non-object value,</li>
7109<li>the second argument is any other non-array value, or contains non-object items.</li>
7110</ul>
7111</li>
7112</ul>
7113</li>
7114<li>
7115
7116<p>Example:</p>
7117
7118<div>
7119<div>
7120<pre class="source">object_add_fields(
7121 {
7122 &quot;id&quot;:1,
7123 &quot;project&quot;:&quot;AsterixDB&quot;,
7124 &quot;address&quot;:{&quot;city&quot;:&quot;Irvine&quot;, &quot;state&quot;:&quot;CA&quot;},
7125 &quot;related&quot;:[&quot;Hivestrix&quot;, &quot;Preglix&quot;, &quot;Apache VXQuery&quot;]
7126 },
7127 [{&quot;field-name&quot;:&quot;employment_location&quot;, &quot;field-value&quot;:create_point(30.0,70.0)}]
7128 );
7129</pre></div></div>
7130</li>
7131<li>
7132
7133<p>The expected result is:</p>
7134
7135<div>
7136<div>
7137<pre class="source">{
7138 &quot;id&quot;:1,
7139 &quot;project&quot;:&quot;AsterixDB&quot;,
7140 &quot;address&quot;:{&quot;city&quot;:&quot;Irvine&quot;, &quot;state&quot;:&quot;CA&quot;},
7141 &quot;related&quot;:[&quot;Hivestrix&quot;, &quot;Preglix&quot;, &quot;Apache VXQuery&quot;]
7142 &quot;employment_location&quot;: point(&quot;30.0,70.0&quot;)
7143 }
7144</pre></div></div>
7145</li>
7146</ul></div>
7147<div class="section">
7148<h3><a name="object_merge"></a>object_merge</h3>
7149<ul>
7150
7151<li>
7152
7153<p>Syntax:</p>
7154
7155<div>
7156<div>
7157<pre class="source">object_merge(object1, object2)
7158</pre></div></div>
7159</li>
7160<li>
7161
7162<p>Merge two different objects into a new object.</p>
7163</li>
7164<li>Arguments:
7165<ul>
7166
7167<li><tt>object1</tt> : a object value.</li>
7168<li><tt>object2</tt> : a object value.</li>
7169</ul>
7170</li>
7171<li>Return Value:
7172<ul>
7173
7174<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>
7175<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
7176<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
7177<li>any other non-object input value will cause a type error.</li>
7178</ul>
7179</li>
7180<li>
7181
7182<p>Example:</p>
7183
7184<div>
7185<div>
7186<pre class="source">object_merge(
7187 {
7188 &quot;id&quot;:1,
7189 &quot;project&quot;:&quot;AsterixDB&quot;,
7190 &quot;address&quot;:{&quot;city&quot;:&quot;Irvine&quot;, &quot;state&quot;:&quot;CA&quot;},
7191 &quot;related&quot;:[&quot;Hivestrix&quot;, &quot;Preglix&quot;, &quot;Apache VXQuery&quot;]
7192 },
7193 {
7194 &quot;user_id&quot;: 22,
7195 &quot;employer&quot;: &quot;UC Irvine&quot;,
7196 &quot;employment_type&quot;: &quot;visitor&quot;
7197 }
7198 );
7199</pre></div></div>
7200</li>
7201<li>
7202
7203<p>The expected result is:</p>
7204
7205<div>
7206<div>
7207<pre class="source">{
7208 &quot;employment_type&quot;: &quot;visitor&quot;,
7209 &quot;address&quot;: {
7210 &quot;city&quot;: &quot;Irvine&quot;,
7211 &quot;state&quot;: &quot;CA&quot;
7212 },
7213 &quot;related&quot;: [
7214 &quot;Hivestrix&quot;,
7215 &quot;Preglix&quot;,
7216 &quot;Apache VXQuery&quot;
7217 ],
7218 &quot;user_id&quot;: 22,
7219 &quot;project&quot;: &quot;AsterixDB&quot;,
7220 &quot;employer&quot;: &quot;UC Irvine&quot;,
7221 &quot;id&quot;: 1
7222}
7223</pre></div></div>
7224</li>
7225</ul></div>
7226<div class="section">
7227<h3><a name="object_length"></a>object_length</h3>
7228<ul>
7229
7230<li>
7231
7232<p>Syntax:</p>
7233
7234<div>
7235<div>
7236<pre class="source">object_length(input_object)
7237</pre></div></div>
7238</li>
7239<li>
7240
7241<p>Returns number of top-level fields in the given object</p>
7242</li>
7243<li>Arguments:
7244<ul>
7245
7246<li><tt>input_object</tt> : an object value.</li>
7247</ul>
7248</li>
7249<li>Return Value:
7250<ul>
7251
7252<li>an integer that represents the number of top-level fields in the given object,</li>
7253<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
7254<li><tt>null</tt> if the argument is a <tt>null</tt> value or any other non-object value</li>
7255</ul>
7256</li>
7257<li>
7258
7259<p>Example:</p>
7260
7261<div>
7262<div>
7263<pre class="source">object_length(
7264 {
7265 &quot;id&quot;: 1,
7266 &quot;project&quot;: &quot;AsterixDB&quot;,
7267 &quot;address&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;},
7268 }
7269 );
7270</pre></div></div>
7271</li>
7272<li>
7273
7274<p>The expected result is:</p>
7275
7276<div>
7277<div>
7278<pre class="source">3
7279</pre></div></div>
7280</li>
7281</ul></div>
7282<div class="section">
7283<h3><a name="object_names"></a>object_names</h3>
7284<ul>
7285
7286<li>
7287
7288<p>Syntax:</p>
7289
7290<div>
7291<div>
7292<pre class="source">object_names(input_object)
7293</pre></div></div>
7294</li>
7295<li>
7296
7297<p>Returns names of top-level fields in the given object</p>
7298</li>
7299<li>Arguments:
7300<ul>
7301
7302<li><tt>input_object</tt> : an object value.</li>
7303</ul>
7304</li>
7305<li>Return Value:
7306<ul>
7307
7308<li>an array with top-level field names of the given object,</li>
7309<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
7310<li><tt>null</tt> if the argument is a <tt>null</tt> value or any other non-object value</li>
7311</ul>
7312</li>
7313<li>
7314
7315<p>Example:</p>
7316
7317<div>
7318<div>
7319<pre class="source">object_names(
7320 {
7321 &quot;id&quot;: 1,
7322 &quot;project&quot;: &quot;AsterixDB&quot;,
7323 &quot;address&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;},
7324 }
7325 );
7326</pre></div></div>
7327</li>
7328<li>
7329
7330<p>The expected result is:</p>
7331
7332<div>
7333<div>
7334<pre class="source">[ &quot;id&quot;, &quot;project&quot;, &quot;address&quot; ]
7335</pre></div></div>
7336</li>
7337</ul></div>
7338<div class="section">
7339<h3><a name="object_remove"></a>object_remove</h3>
7340<ul>
7341
7342<li>
7343
7344<p>Syntax:</p>
7345
7346<div>
7347<div>
7348<pre class="source">object_remove(input_object, field_name)
7349</pre></div></div>
7350</li>
7351<li>
7352
7353<p>Returns a new object that has the same fields as the input object except the field to be removed</p>
7354</li>
7355<li>Arguments:
7356<ul>
7357
7358<li><tt>input_object</tt> : an object value.</li>
7359<li><tt>field_name</tt> : a string field name.</li>
7360</ul>
7361</li>
7362<li>Return Value:
7363<ul>
7364
7365<li>A new object that has the same fields as <tt>input_object</tt> except the field <tt>field_name</tt>,</li>
7366<li><tt>missing</tt> if the argument <tt>input_object</tt> or <tt>field_name</tt> is missing,</li>
7367<li><tt>null</tt> if the argument <tt>input_object</tt> is <tt>null</tt> or any other non-object value, or the argument <tt>field_name</tt> is <tt>null</tt> or any other non-string value.</li>
7368</ul>
7369</li>
7370<li>
7371
7372<p>Example:</p>
7373
7374<div>
7375<div>
7376<pre class="source">object_remove(
7377 {
7378 &quot;id&quot;: 1,
7379 &quot;project&quot;: &quot;AsterixDB&quot;,
7380 &quot;address&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;}
7381 }
7382 , &quot;address&quot;
7383 );
7384</pre></div></div>
7385</li>
7386<li>
7387
7388<p>The expected result is:</p>
7389
7390<div>
7391<div>
7392<pre class="source">{
7393 &quot;id&quot;: 1,
7394 &quot;project&quot;: &quot;AsterixDB&quot;,
7395}
7396</pre></div></div>
7397</li>
7398</ul></div>
7399<div class="section">
7400<h3><a name="object_rename"></a>object_rename</h3>
7401<ul>
7402
7403<li>
7404
7405<p>Syntax:</p>
7406
7407<div>
7408<div>
7409<pre class="source">object_rename(input_object, old_field, new_field)
7410</pre></div></div>
7411</li>
7412<li>
7413
7414<p>Returns a new object that has the same fields as <tt>input_object</tt> with field <tt>old_field</tt> replaced by <tt>new_field</tt></p>
7415</li>
7416<li>Arguments:
7417<ul>
7418
7419<li><tt>input_object</tt> : an object value.</li>
7420<li><tt>old_field</tt> : a string representing the old (original) field name inside the object <tt>input_object</tt>.</li>
7421<li><tt>new_field</tt> : a string representing the new field name to replace <tt>old_field</tt> inside the object <tt>input_object</tt>.</li>
7422</ul>
7423</li>
7424<li>Return Value:
7425<ul>
7426
7427<li>A new object that has the same fields as <tt>input_object</tt> with field <tt>old_field</tt> replaced by <tt>new_field</tt>,</li>
7428<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
7429<li><tt>null</tt> if any argument is <tt>null</tt> or <tt>input_object</tt> is non-object value, or <tt>old_field</tt> is non-string value, or <tt>new_field</tt> is any non-string value.</li>
7430</ul>
7431</li>
7432<li>
7433
7434<p>Example:</p>
7435
7436<div>
7437<div>
7438<pre class="source">object_rename(
7439 {
7440 &quot;id&quot;: 1,
7441 &quot;project&quot;: &quot;AsterixDB&quot;,
7442 &quot;address&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;}
7443 }
7444 , &quot;address&quot;
7445 , &quot;location&quot;
7446 );
7447</pre></div></div>
7448</li>
7449<li>
7450
7451<p>The expected result is:</p>
7452
7453<div>
7454<div>
7455<pre class="source">{
7456 &quot;id&quot;: 1,
7457 &quot;project&quot;: &quot;AsterixDB&quot;,
7458 &quot;location&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;}
7459}
7460</pre></div></div>
7461</li>
7462</ul></div>
7463<div class="section">
7464<h3><a name="object_unwrap"></a>object_unwrap</h3>
7465<ul>
7466
7467<li>
7468
7469<p>Syntax:</p>
7470
7471<div>
7472<div>
7473<pre class="source">object_unwrap(input_object)
7474</pre></div></div>
7475</li>
7476<li>
7477
7478<p>Returns the value of the single name-value pair that appears in <tt>input_object</tt>.</p>
7479</li>
7480<li>Arguments:
7481<ul>
7482
7483<li><tt>input_object</tt> : an object value that consists of exactly one name-value pair.</li>
7484</ul>
7485</li>
7486<li>Return Value:
7487<ul>
7488
7489<li>The value of the single name-value pair that appears in <tt>input_object</tt>,</li>
7490<li><tt>missing</tt> if <tt>input_object</tt> is <tt>missing</tt>,</li>
7491<li><tt>null</tt> if <tt>input_object</tt> is null, or an empty object, or there is more than one name-value pair in <tt>input_object</tt>, or any non-object value.</li>
7492</ul>
7493</li>
7494<li>
7495
7496<p>Example:</p>
7497
7498<div>
7499<div>
7500<pre class="source">object_unwrap(
7501 {
7502 &quot;id&quot;: 1
7503 }
7504 );
7505</pre></div></div>
7506</li>
7507<li>
7508
7509<p>The expected result is:</p>
7510
7511<div>
7512<div>
7513<pre class="source">{
7514 1
7515}
7516</pre></div></div>
7517</li>
7518</ul></div>
7519<div class="section">
7520<h3><a name="object_replace"></a>object_replace</h3>
7521<ul>
7522
7523<li>
7524
7525<p>Syntax:</p>
7526
7527<div>
7528<div>
7529<pre class="source">object_replace(input_object, old_value, new_value)
7530</pre></div></div>
7531</li>
7532<li>
7533
7534<p>Returns a new object that has the same fields as <tt>input_object</tt> with all occurrences of value <tt>old_value</tt> replaced by <tt>new_value</tt></p>
7535</li>
7536<li>Arguments:
7537<ul>
7538
7539<li><tt>input_object</tt> : an object value.</li>
7540<li><tt>old_value</tt> : a primitive type value to be replaced by <tt>new_value</tt>.</li>
7541<li><tt>new_value</tt> : a value to replace <tt>old_value</tt>.</li>
7542</ul>
7543</li>
7544<li>Return Value:
7545<ul>
7546
7547<li>A new object that has the same fields as <tt>input_object</tt> with all occurrences of value <tt>old_value</tt> replaced by <tt>new_value</tt>,</li>
7548<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
7549<li><tt>null</tt> if <tt>input_object</tt> or <tt>old_value</tt> is null,</li>
7550<li>a type error will be raised if:
7551<ul>
7552
7553<li><tt>old_value</tt> is not a primitive type value.</li>
7554</ul>
7555</li>
7556</ul>
7557</li>
7558<li>
7559
7560<p>Example:</p>
7561
7562<div>
7563<div>
7564<pre class="source">object_replace(
7565 {
7566 &quot;id&quot;: 1,
7567 &quot;project&quot;: &quot;AsterixDB&quot;,
7568 &quot;address&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;}
7569 }
7570 , &quot;AsterixDB&quot;
7571 , &quot;Apache AsterixDB&quot;
7572 );
7573</pre></div></div>
7574</li>
7575<li>
7576
7577<p>The expected result is:</p>
7578
7579<div>
7580<div>
7581<pre class="source">{
7582 &quot;id&quot;: 1,
7583 &quot;project&quot;: &quot;Apache AsterixDB&quot;,
7584 &quot;location&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;}
7585}
7586</pre></div></div>
7587</li>
7588</ul></div>
7589<div class="section">
7590<h3><a name="object_add"></a>object_add</h3>
7591<ul>
7592
7593<li>
7594
7595<p>Syntax:</p>
7596
7597<div>
7598<div>
7599<pre class="source">object_add(input_object, field_name, field_value)
7600</pre></div></div>
7601</li>
7602<li>
7603
7604<p>Returns a new object that has the same fields as <tt>input_object</tt> as well as the new field <tt>field_name</tt>.</p>
7605</li>
7606<li>Arguments:
7607<ul>
7608
7609<li><tt>input_object</tt> : an object value.</li>
7610<li><tt>field_name</tt> : a string representing a field name to be added.</li>
7611<li><tt>field_value</tt> : a value to be assigned to the new field <tt>field_name</tt>.</li>
7612</ul>
7613</li>
7614<li>Return Value:
7615<ul>
7616
7617<li>A new object that has the same fields as <tt>input_object</tt> as well as the new field <tt>field_name</tt>,</li>
7618<li><tt>missing</tt> if <tt>input_object</tt> or <tt>field_name</tt> is <tt>missing</tt>,</li>
7619<li><tt>null</tt> if <tt>input_object</tt> or <tt>field_name</tt> is <tt>null</tt>, or <tt>input_object</tt> is not an object, or <tt>field_name</tt> is not a string,</li>
7620<li><tt>input_object</tt> if <tt>field_name</tt>already exists in <tt>input_object</tt> or <tt>field_value</tt> is missing.</li>
7621</ul>
7622</li>
7623<li>
7624
7625<p>Example:</p>
7626
7627<div>
7628<div>
7629<pre class="source">object_add(
7630 {
7631 &quot;id&quot;: 1,
7632 &quot;project&quot;: &quot;AsterixDB&quot;,
7633 &quot;address&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;}
7634 }
7635 , &quot;company&quot;
7636 , &quot;Apache&quot;
7637 );
7638</pre></div></div>
7639</li>
7640<li>
7641
7642<p>The expected result is:</p>
7643
7644<div>
7645<div>
7646<pre class="source">{
7647 &quot;id&quot;: 1,
7648 &quot;project&quot;: &quot;AsterixDB&quot;,
7649 &quot;location&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;},
7650 &quot;company&quot;: &quot;Apache&quot;
7651}
7652</pre></div></div>
7653</li>
7654</ul></div>
7655<div class="section">
7656<h3><a name="object_put"></a>object_put</h3>
7657<ul>
7658
7659<li>
7660
7661<p>Syntax:</p>
7662
7663<div>
7664<div>
7665<pre class="source">object_put(input_object, field_name, field_value)
7666</pre></div></div>
7667</li>
7668<li>
7669
7670<p>Adds, modifies, or removes a field of an object.</p>
7671</li>
7672<li>Arguments:
7673<ul>
7674
7675<li><tt>input_object</tt> : an object value.</li>
7676<li><tt>field_name</tt> : a string representing a field name to be added.</li>
7677<li><tt>field_value</tt> : a value to be assigned to the new field <tt>field_name</tt>.</li>
7678</ul>
7679</li>
7680<li>Return Value:
7681<ul>
7682
7683<li>a new object that has the same fields as <tt>input_object</tt> as well as the new field <tt>field_name</tt>, or with updated <tt>field_name</tt> value to <tt>field_value</tt> if <tt>field_name</tt> already exists in <tt>input_object</tt>, or with <tt>field_name</tt>removed if <tt>field_name</tt> already exists in <tt>input_object</tt> and <tt>field_value</tt> is <tt>missing</tt>,</li>
7684<li><tt>missing</tt> if <tt>input_object</tt> or <tt>field_name</tt> is <tt>missing</tt>,</li>
7685<li><tt>null</tt> if <tt>input_object</tt> or <tt>field_name</tt> is <tt>null</tt>, or <tt>input_object</tt> is not an object, or <tt>field_name</tt> is not not a string.</li>
7686</ul>
7687</li>
7688<li>
7689
7690<p>Example:</p>
7691
7692<div>
7693<div>
7694<pre class="source">object_put(
7695 {
7696 &quot;id&quot;: 1,
7697 &quot;project&quot;: &quot;AsterixDB&quot;,
7698 &quot;address&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;}
7699 }
7700 , &quot;project&quot;
7701 , &quot;Apache AsterixDB&quot;
7702 );
7703</pre></div></div>
7704</li>
7705<li>
7706
7707<p>The expected result is:</p>
7708
7709<div>
7710<div>
7711<pre class="source">{
7712 &quot;id&quot;: 1,
7713 &quot;project&quot;: &quot;Apache AsterixDB&quot;,
7714 &quot;location&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;}
7715}
7716</pre></div></div>
7717</li>
7718</ul></div>
7719<div class="section">
7720<h3><a name="object_values"></a>object_values</h3>
7721<ul>
7722
7723<li>
7724
7725<p>Syntax:</p>
7726
7727<div>
7728<div>
7729<pre class="source">object_values(input_object)
7730</pre></div></div>
7731</li>
7732<li>
7733
7734<p>Returns an array of the values of the fields in <tt>input_object</tt>.</p>
7735</li>
7736<li>Arguments:
7737<ul>
7738
7739<li><tt>input_object</tt> : an object value.</li>
7740</ul>
7741</li>
7742<li>Return Value:
7743<ul>
7744
7745<li>An array of the values of the fields in <tt>input_object</tt>,</li>
7746<li><tt>missing</tt> if <tt>input_object</tt> is <tt>missing</tt>,</li>
7747<li><tt>null</tt> if <tt>input_object</tt> is null or any non-object value.</li>
7748</ul>
7749</li>
7750<li>
7751
7752<p>Example:</p>
7753
7754<div>
7755<div>
7756<pre class="source">object_values(
7757 {
7758 &quot;id&quot;: 1,
7759 &quot;project&quot;: &quot;AsterixDB&quot;,
7760 &quot;address&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;}
7761 }
7762 );
7763</pre></div></div>
7764</li>
7765<li>
7766
7767<p>The expected result is:</p>
7768
7769<div>
7770<div>
7771<pre class="source">[
7772 1,
7773 &quot;AsterixDB&quot;,
7774 {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;}
7775]
7776</pre></div></div>
7777</li>
7778</ul></div>
7779<div class="section">
7780<h3><a name="object_pairs"></a>object_pairs</h3>
7781<ul>
7782
7783<li>
7784
7785<p>Syntax:</p>
7786
7787<div>
7788<div>
7789<pre class="source">object_pairs(input_object)
7790</pre></div></div>
7791</li>
7792<li>
7793
7794<p>Returns an array of objects describing fields of <tt>input_object</tt>. For each field of the <tt>input_object</tt> the returned array contains an object with two fields <tt>name</tt> and <tt>value</tt> which are set to the <tt>input_object</tt>&#x2019;s field name and value.</p>
7795</li>
7796<li>
7797
7798<p>Arguments:</p>
7799<ul>
7800
7801<li><tt>input_object</tt> : an object value.</li>
7802</ul>
7803</li>
7804<li>Return Value:
7805<ul>
7806
7807<li>An array of the <tt>name</tt>/<tt>value</tt> pairs of the fields in <tt>input_object</tt>,</li>
7808<li><tt>missing</tt> if <tt>input_object</tt> is <tt>missing</tt>,</li>
7809<li><tt>null</tt> if <tt>input_object</tt> is null or any non-object value.</li>
7810</ul>
7811</li>
7812<li>
7813
7814<p>Example:</p>
7815
7816<div>
7817<div>
7818<pre class="source">object_pairs(
7819 {
7820 &quot;id&quot;: 1,
7821 &quot;project&quot;: &quot;AsterixDB&quot;,
7822 &quot;address&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;}
7823 }
7824 );
7825</pre></div></div>
7826</li>
7827<li>
7828
7829<p>The expected result is:</p>
7830
7831<div>
7832<div>
7833<pre class="source">[
7834 { &quot;name&quot;: &quot;id&quot;, &quot;value&quot;: 1 },
7835 { &quot;name&quot;: &quot;project&quot;, &quot;value&quot;: &quot;AsterixDB&quot; },
7836 { &quot;name&quot;: &quot;address&quot;, &quot;value&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;} }
7837]
7838</pre></div></div>
7839</li>
7840</ul></div>
7841<div class="section">
7842<h3><a name="pairs"></a>pairs</h3>
7843<ul>
7844
7845<li>
7846
7847<p>Syntax:</p>
7848
7849<div>
7850<div>
7851<pre class="source">pairs(input_object)
7852</pre></div></div>
7853</li>
7854<li>
7855
7856<p>Returns an array of arrays describing fields of <tt>input_object</tt>, including nested fields. For each field of the <tt>input_object</tt> the returned array contains an array with two elements. The first element is the name and the second one is the value of the <tt>input_object</tt>&#x2019;s field. The input object is introspected recursively, so all fields of its nested objects are returned. Nested objects contained in arrays and multisets are also processed by this function.</p>
7857</li>
7858<li>
7859
7860<p>Arguments:</p>
7861<ul>
7862
7863<li><tt>input_object</tt> : an object value (or an array or a multiset)</li>
7864</ul>
7865</li>
7866<li>Return Value:
7867<ul>
7868
7869<li>An array of arrays with name, value pairs of the fields in <tt>input_object</tt>, including nested fields. Each inner array has exactly two items: name and value of the <tt>input_object</tt>&#x2019;s field.</li>
7870<li><tt>missing</tt> if <tt>input_object</tt> is <tt>missing</tt>,</li>
7871<li><tt>null</tt> if <tt>input_object</tt> is null or a value of a primitive data type.</li>
7872</ul>
7873</li>
7874<li>
7875
7876<p>Example:</p>
7877
7878<div>
7879<div>
7880<pre class="source">pairs(
7881 {
7882 &quot;id&quot;: 1,
7883 &quot;project&quot;: &quot;AsterixDB&quot;,
7884 &quot;address&quot;: {&quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot;}
7885 }
7886 );
7887</pre></div></div>
7888</li>
7889<li>
7890
7891<p>The expected result is:</p>
7892
7893<div>
7894<div>
7895<pre class="source">[
7896 [ &quot;id&quot;, 1 ],
7897 [ &quot;project&quot;, &quot;AsterixDB&quot; ],
7898 [ &quot;address&quot;, { &quot;city&quot;: &quot;Irvine&quot;, &quot;state&quot;: &quot;CA&quot; } ],
7899 [ &quot;city&quot;, &quot;Irvine&quot; ],
7900 [ &quot;state&quot;, &quot;CA&quot; ]
7901]
7902</pre></div></div>
7903</li>
7904</ul><!--
7905 ! Licensed to the Apache Software Foundation (ASF) under one
7906 ! or more contributor license agreements. See the NOTICE file
7907 ! distributed with this work for additional information
7908 ! regarding copyright ownership. The ASF licenses this file
7909 ! to you under the Apache License, Version 2.0 (the
7910 ! "License"); you may not use this file except in compliance
7911 ! with the License. You may obtain a copy of the License at
7912 !
7913 ! http://www.apache.org/licenses/LICENSE-2.0
7914 !
7915 ! Unless required by applicable law or agreed to in writing,
7916 ! software distributed under the License is distributed on an
7917 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
7918 ! KIND, either express or implied. See the License for the
7919 ! specific language governing permissions and limitations
7920 ! under the License.
7921 !-->
7922</div></div>
7923<div class="section">
7924<h2><a name="Aggregate_Functions_.28Array_Functions.29"></a><a name="AggregateFunctions" id="AggregateFunctions">Aggregate Functions (Array Functions) </a></h2>
7925<p>This section contains detailed descriptions of the built-in aggregate functions in the query language.</p>
7926<p>The query language also supports standard SQL aggregate functions (e.g., <tt>MIN</tt>, <tt>MAX</tt>, <tt>SUM</tt>, <tt>COUNT</tt>, and <tt>AVG</tt>). Note that these are not real functions in the query language, but just syntactic sugars over corresponding builtin aggregate functions (e.g., <tt>ARRAY_MIN</tt>, <tt>ARRAY_MAX</tt>, <tt>ARRAY_SUM</tt>, <tt>ARRAY_COUNT</tt>, and <tt>ARRAY_AVG</tt>). Refer to <a href="manual.html#Aggregation_PseudoFunctions">Aggregation Pseudo-Functions</a> for details.</p>
7927<p>The <tt>DISTINCT</tt> keyword may be used with built-in aggregate functions and standard SQL aggregate functions. It may also be used with aggregate functions used as window functions. It determines whether the function aggregates all values in the group, or distinct values only. Refer to <a href="manual.html#Function_call_expressions">Function Calls</a> for details.</p>
7928<p>Aggregate functions may be used as window functions when they are used with an OVER clause. Refer to <a href="manual.html#Over_clauses">OVER Clauses</a> for details.</p>
7929<div class="section">
7930<h3><a name="array_count"></a>array_count</h3>
7931<ul>
7932
7933<li>
7934
7935<p>Syntax:</p>
7936
7937<div>
7938<div>
7939<pre class="source">array_count(collection)
7940</pre></div></div>
7941</li>
7942<li>
7943
7944<p>Gets the number of non-null and non-missing items in the given collection.</p>
7945</li>
7946<li>Arguments:
7947<ul>
7948
7949<li><tt>collection</tt> could be:
7950<ul>
7951
7952<li>an <tt>array</tt> or <tt>multiset</tt> to be counted,</li>
7953<li>or, a <tt>null</tt> value,</li>
7954<li>or, a <tt>missing</tt> value.</li>
7955</ul>
7956</li>
7957</ul>
7958</li>
7959<li>Return Value:
7960<ul>
7961
7962<li>a <tt>bigint</tt> value representing the number of non-null and non-missing items in the given collection,</li>
7963<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
7964<li>any other non-array and non-multiset input value will cause an error.</li>
7965</ul>
7966</li>
7967<li>
7968
7969<p>Example:</p>
7970
7971<div>
7972<div>
7973<pre class="source">array_count( ['hello', 'world', 1, 2, 3, null, missing] );
7974</pre></div></div>
7975</li>
7976<li>
7977
7978<p>The expected result is:</p>
7979
7980<div>
7981<div>
7982<pre class="source">5
7983</pre></div></div>
7984</li>
7985</ul></div>
7986<div class="section">
7987<h3><a name="array_avg"></a>array_avg</h3>
7988<ul>
7989
7990<li>
7991
7992<p>Syntax:</p>
7993
7994<div>
7995<div>
7996<pre class="source">array_avg(num_collection)
7997</pre></div></div>
7998</li>
7999<li>
8000
8001<p>Gets the average value of the non-null and non-missing numeric items in the given collection.</p>
8002</li>
8003<li>Arguments:
8004<ul>
8005
8006<li><tt>num_collection</tt> could be:
8007<ul>
8008
8009<li>an <tt>array</tt> or <tt>multiset</tt> containing numeric values, <tt>null</tt>s or <tt>missing</tt>s,</li>
8010<li>or, a <tt>null</tt> value,</li>
8011<li>or, a <tt>missing</tt> value.</li>
8012</ul>
8013</li>
8014</ul>
8015</li>
8016<li>Return Value:
8017<ul>
8018
8019<li>a <tt>double</tt> value representing the average of the non-null and non-missing numbers in the given collection,</li>
8020<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
8021<li><tt>null</tt> is returned if the given collection does not contain any non-null and non-missing items,</li>
8022<li>any other non-array and non-multiset input value will cause a type error,</li>
8023<li>any other non-numeric value in the input collection will cause a type error.</li>
8024</ul>
8025</li>
8026<li>
8027
8028<p>Example:</p>
8029
8030<div>
8031<div>
8032<pre class="source">array_avg( [1.2, 2.3, 3.4, 0, null] );
8033</pre></div></div>
8034</li>
8035<li>
8036
8037<p>The expected result is:</p>
8038
8039<div>
8040<div>
8041<pre class="source">1.725
8042</pre></div></div>
8043</li>
8044</ul></div>
8045<div class="section">
8046<h3><a name="array_sum"></a>array_sum</h3>
8047<ul>
8048
8049<li>
8050
8051<p>Syntax:</p>
8052
8053<div>
8054<div>
8055<pre class="source">array_sum(num_collection)
8056</pre></div></div>
8057</li>
8058<li>
8059
8060<p>Gets the sum of non-null and non-missing items in the given collection.</p>
8061</li>
8062<li>Arguments:
8063<ul>
8064
8065<li><tt>num_collection</tt> could be:
8066<ul>
8067
8068<li>an <tt>array</tt> or <tt>multiset</tt> containing numeric values, <tt>null</tt>s or <tt>missing</tt>s,</li>
8069<li>or, a <tt>null</tt> value,</li>
8070<li>or, a <tt>missing</tt> value.</li>
8071</ul>
8072</li>
8073</ul>
8074</li>
8075<li>Return Value:
8076<ul>
8077
8078<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>
8079<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
8080<li><tt>null</tt> is returned if the given collection does not contain any non-null and non-missing items,</li>
8081<li>any other non-array and non-multiset input value will cause a type error,</li>
8082<li>any other non-numeric value in the input collection will cause a type error.</li>
8083</ul>
8084</li>
8085<li>
8086
8087<p>Example:</p>
8088
8089<div>
8090<div>
8091<pre class="source">array_sum( [1.2, 2.3, 3.4, 0, null, missing] );
8092</pre></div></div>
8093</li>
8094<li>
8095
8096<p>The expected result is:</p>
8097
8098<div>
8099<div>
8100<pre class="source">6.9
8101</pre></div></div>
8102</li>
8103</ul></div>
8104<div class="section">
8105<h3><a name="array_min"></a>array_min</h3>
8106<ul>
8107
8108<li>
8109
8110<p>Syntax:</p>
8111
8112<div>
8113<div>
8114<pre class="source">array_min(num_collection)
8115</pre></div></div>
8116</li>
8117<li>
8118
8119<p>Gets the min value of non-null and non-missing comparable items in the given collection.</p>
8120</li>
8121<li>Arguments:
8122<ul>
8123
8124<li><tt>num_collection</tt> could be:
8125<ul>
8126
8127<li>an <tt>array</tt> or <tt>multiset</tt>,</li>
8128<li>or, a <tt>null</tt> value,</li>
8129<li>or, a <tt>missing</tt> value.</li>
8130</ul>
8131</li>
8132</ul>
8133</li>
8134<li>Return Value:
8135<ul>
8136
8137<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>
8138<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
8139<li><tt>null</tt> is returned if the given collection does not contain any non-null and non-missing items,</li>
8140<li>multiple incomparable items in the input array or multiset will cause a type error,</li>
8141<li>any other non-array and non-multiset input value will cause a type error.</li>
8142</ul>
8143</li>
8144<li>
8145
8146<p>Example:</p>
8147
8148<div>
8149<div>
8150<pre class="source">array_min( [1.2, 2.3, 3.4, 0, null, missing] );
8151</pre></div></div>
8152</li>
8153<li>
8154
8155<p>The expected result is:</p>
8156
8157<div>
8158<div>
8159<pre class="source">0.0
8160</pre></div></div>
8161</li>
8162</ul></div>
8163<div class="section">
8164<h3><a name="array_max"></a>array_max</h3>
8165<ul>
8166
8167<li>
8168
8169<p>Syntax:</p>
8170
8171<div>
8172<div>
8173<pre class="source">array_max(num_collection)
8174</pre></div></div>
8175</li>
8176<li>
8177
8178<p>Gets the max value of the non-null and non-missing comparable items in the given collection.</p>
8179</li>
8180<li>Arguments:
8181<ul>
8182
8183<li><tt>num_collection</tt> could be:
8184<ul>
8185
8186<li>an <tt>array</tt> or <tt>multiset</tt>,</li>
8187<li>or, a <tt>null</tt> value,</li>
8188<li>or, a <tt>missing</tt> value.</li>
8189</ul>
8190</li>
8191</ul>
8192</li>
8193<li>Return Value:
8194<ul>
8195
8196<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>
8197<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
8198<li><tt>null</tt> is returned if the given collection does not contain any non-null and non-missing items,</li>
8199<li>multiple incomparable items in the input array or multiset will cause a type error,</li>
8200<li>any other non-array and non-multiset input value will cause a type error.</li>
8201</ul>
8202</li>
8203<li>
8204
8205<p>Example:</p>
8206
8207<div>
8208<div>
8209<pre class="source">array_max( [1.2, 2.3, 3.4, 0, null, missing] );
8210</pre></div></div>
8211</li>
8212<li>
8213
8214<p>The expected result is:</p>
8215
8216<div>
8217<div>
8218<pre class="source">3.4
8219</pre></div></div>
8220</li>
8221</ul></div>
8222<div class="section">
8223<h3><a name="array_stddev_samp"></a>array_stddev_samp</h3>
8224<ul>
8225
8226<li>
8227
8228<p>Syntax:</p>
8229
8230<div>
8231<div>
8232<pre class="source">array_stddev_samp(num_collection)
8233</pre></div></div>
8234</li>
8235<li>
8236
8237<p>Gets the sample standard deviation value of the non-null and non-missing numeric items in the given collection.</p>
8238</li>
8239<li>Arguments:
8240<ul>
8241
8242<li><tt>num_collection</tt> could be:
8243<ul>
8244
8245<li>an <tt>array</tt> or <tt>multiset</tt> containing numeric values, <tt>null</tt>s or <tt>missing</tt>s,</li>
8246<li>or, a <tt>null</tt> value,</li>
8247<li>or, a <tt>missing</tt> value.</li>
8248</ul>
8249</li>
8250</ul>
8251</li>
8252<li>Return Value:
8253<ul>
8254
8255<li>a <tt>double</tt> value representing the sample standard deviation of the non-null and non-missing numbers in the given collection,</li>
8256<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
8257<li><tt>null</tt> is returned if the given collection does not contain any non-null and non-missing items,</li>
8258<li>any other non-array and non-multiset input value will cause a type error,</li>
8259<li>any other non-numeric value in the input collection will cause a type error.</li>
8260</ul>
8261</li>
8262<li>
8263
8264<p>Example:</p>
8265
8266<div>
8267<div>
8268<pre class="source">array_stddev_samp( [1.2, 2.3, 3.4, 0, null] );
8269</pre></div></div>
8270</li>
8271<li>
8272
8273<p>The expected result is:</p>
8274
8275<div>
8276<div>
8277<pre class="source">1.4591664287073858
8278</pre></div></div>
8279</li>
8280</ul></div>
8281<div class="section">
8282<h3><a name="array_stddev_pop"></a>array_stddev_pop</h3>
8283<ul>
8284
8285<li>
8286
8287<p>Syntax:</p>
8288
8289<div>
8290<div>
8291<pre class="source">array_stddev_pop(num_collection)
8292</pre></div></div>
8293</li>
8294<li>
8295
8296<p>Gets the population standard deviation value of the non-null and non-missing numeric items in the given collection.</p>
8297</li>
8298<li>Arguments:
8299<ul>
8300
8301<li><tt>num_collection</tt> could be:
8302<ul>
8303
8304<li>an <tt>array</tt> or <tt>multiset</tt> containing numeric values, <tt>null</tt>s or <tt>missing</tt>s,</li>
8305<li>or, a <tt>null</tt> value,</li>
8306<li>or, a <tt>missing</tt> value.</li>
8307</ul>
8308</li>
8309</ul>
8310</li>
8311<li>Return Value:
8312<ul>
8313
8314<li>a <tt>double</tt> value representing the population standard deviation of the non-null and non-missing numbers in the given collection,</li>
8315<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
8316<li><tt>null</tt> is returned if the given collection does not contain any non-null and non-missing items,</li>
8317<li>any other non-array and non-multiset input value will cause a type error,</li>
8318<li>any other non-numeric value in the input collection will cause a type error.</li>
8319</ul>
8320</li>
8321<li>
8322
8323<p>Example:</p>
8324
8325<div>
8326<div>
8327<pre class="source">array_stddev_pop( [1.2, 2.3, 3.4, 0, null] );
8328</pre></div></div>
8329</li>
8330<li>
8331
8332<p>The expected result is:</p>
8333
8334<div>
8335<div>
8336<pre class="source">1.2636751956100112
8337</pre></div></div>
8338</li>
8339</ul></div>
8340<div class="section">
8341<h3><a name="array_var_samp"></a>array_var_samp</h3>
8342<ul>
8343
8344<li>
8345
8346<p>Syntax:</p>
8347
8348<div>
8349<div>
8350<pre class="source">array_var_samp(num_collection)
8351</pre></div></div>
8352</li>
8353<li>
8354
8355<p>Gets the sample variance value of the non-null and non-missing numeric items in the given collection.</p>
8356</li>
8357<li>Arguments:
8358<ul>
8359
8360<li><tt>num_collection</tt> could be:
8361<ul>
8362
8363<li>an <tt>array</tt> or <tt>multiset</tt> containing numeric values, <tt>null</tt>s or <tt>missing</tt>s,</li>
8364<li>or, a <tt>null</tt> value,</li>
8365<li>or, a <tt>missing</tt> value.</li>
8366</ul>
8367</li>
8368</ul>
8369</li>
8370<li>Return Value:
8371<ul>
8372
8373<li>a <tt>double</tt> value representing the sample variance of the non-null and non-missing numbers in the given collection,</li>
8374<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
8375<li><tt>null</tt> is returned if the given collection does not contain any non-null and non-missing items,</li>
8376<li>any other non-array and non-multiset input value will cause a type error,</li>
8377<li>any other non-numeric value in the input collection will cause a type error.</li>
8378</ul>
8379</li>
8380<li>
8381
8382<p>Example:</p>
8383
8384<div>
8385<div>
8386<pre class="source">array_var_samp( [1.2, 2.3, 3.4, 0, null] );
8387</pre></div></div>
8388</li>
8389<li>
8390
8391<p>The expected result is:</p>
8392
8393<div>
8394<div>
8395<pre class="source">2.1291666666666664
8396</pre></div></div>
8397</li>
8398</ul></div>
8399<div class="section">
8400<h3><a name="array_var_pop"></a>array_var_pop</h3>
8401<ul>
8402
8403<li>
8404
8405<p>Syntax:</p>
8406
8407<div>
8408<div>
8409<pre class="source">array_var_pop(num_collection)
8410</pre></div></div>
8411</li>
8412<li>
8413
8414<p>Gets the population variance value of the non-null and non-missing numeric items in the given collection.</p>
8415</li>
8416<li>Arguments:
8417<ul>
8418
8419<li><tt>num_collection</tt> could be:
8420<ul>
8421
8422<li>an <tt>array</tt> or <tt>multiset</tt> containing numeric values, <tt>null</tt>s or <tt>missing</tt>s,</li>
8423<li>or, a <tt>null</tt> value,</li>
8424<li>or, a <tt>missing</tt> value.</li>
8425</ul>
8426</li>
8427</ul>
8428</li>
8429<li>Return Value:
8430<ul>
8431
8432<li>a <tt>double</tt> value representing the population variance of the non-null and non-missing numbers in the given collection,</li>
8433<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
8434<li><tt>null</tt> is returned if the given collection does not contain any non-null and non-missing items,</li>
8435<li>any other non-array and non-multiset input value will cause a type error,</li>
8436<li>any other non-numeric value in the input collection will cause a type error.</li>
8437</ul>
8438</li>
8439<li>
8440
8441<p>Example:</p>
8442
8443<div>
8444<div>
8445<pre class="source">array_var_pop( [1.2, 2.3, 3.4, 0, null] );
8446</pre></div></div>
8447</li>
8448<li>
8449
8450<p>The expected result is:</p>
8451
8452<div>
8453<div>
8454<pre class="source">1.5968749999999998
8455</pre></div></div>
8456</li>
8457</ul></div>
8458<div class="section">
8459<h3><a name="array_skewness"></a>array_skewness</h3>
8460<ul>
8461
8462<li>
8463
8464<p>Syntax:</p>
8465
8466<div>
8467<div>
8468<pre class="source">array_skewness(num_collection)
8469</pre></div></div>
8470</li>
8471<li>
8472
8473<p>Gets the skewness value of the non-null and non-missing numeric items in the given collection.</p>
8474</li>
8475<li>Arguments:
8476<ul>
8477
8478<li><tt>num_collection</tt> could be:
8479<ul>
8480
8481<li>an <tt>array</tt> or <tt>multiset</tt> containing numeric values, <tt>null</tt>s or <tt>missing</tt>s,</li>
8482<li>or, a <tt>null</tt> value,</li>
8483<li>or, a <tt>missing</tt> value.</li>
8484</ul>
8485</li>
8486</ul>
8487</li>
8488<li>Return Value:
8489<ul>
8490
8491<li>a <tt>double</tt> value representing the skewness of the non-null and non-missing numbers in the given collection,</li>
8492<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
8493<li><tt>null</tt> is returned if the given collection does not contain any non-null and non-missing items,</li>
8494<li>any other non-array and non-multiset input value will cause a type error,</li>
8495<li>any other non-numeric value in the input collection will cause a type error.</li>
8496</ul>
8497</li>
8498<li>
8499
8500<p>Example:</p>
8501
8502<div>
8503<div>
8504<pre class="source">array_skewness( [1.2, 2.3, 3.4, 0, null] );
8505</pre></div></div>
8506</li>
8507<li>
8508
8509<p>The expected result is:</p>
8510
8511<div>
8512<div>
8513<pre class="source">-0.04808451539164242
8514</pre></div></div>
8515</li>
8516</ul></div>
8517<div class="section">
8518<h3><a name="array_kurtosis"></a>array_kurtosis</h3>
8519<ul>
8520
8521<li>
8522
8523<p>Syntax:</p>
8524
8525<div>
8526<div>
8527<pre class="source">array_kurtosis(num_collection)
8528</pre></div></div>
8529</li>
8530<li>
8531
8532<p>Gets the kurtosis value from the normal distribution of the non-null and non-missing numeric items in the given collection.</p>
8533</li>
8534<li>Arguments:
8535<ul>
8536
8537<li><tt>num_collection</tt> could be:
8538<ul>
8539
8540<li>an <tt>array</tt> or <tt>multiset</tt> containing numeric values, <tt>null</tt>s or <tt>missing</tt>s,</li>
8541<li>or, a <tt>null</tt> value,</li>
8542<li>or, a <tt>missing</tt> value.</li>
8543</ul>
8544</li>
8545</ul>
8546</li>
8547<li>Return Value:
8548<ul>
8549
8550<li>a <tt>double</tt> value representing the kurtosis from a normal distribution of the non-null and non-missing numbers in the given collection,</li>
8551<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
8552<li><tt>null</tt> is returned if the given collection does not contain any non-null and non-missing items,</li>
8553<li>any other non-array and non-multiset input value will cause a type error,</li>
8554<li>any other non-numeric value in the input collection will cause a type error.</li>
8555</ul>
8556</li>
8557<li>
8558
8559<p>Example:</p>
8560
8561<div>
8562<div>
8563<pre class="source">array_kurtosis( [1.2, 2.3, 3.4, 0, null] );
8564</pre></div></div>
8565</li>
8566<li>
8567
8568<p>The expected result is:</p>
8569
8570<div>
8571<div>
8572<pre class="source">-1.342049701096427
8573</pre></div></div>
8574</li>
8575</ul></div>
8576<div class="section">
8577<h3><a name="strict_count"></a>strict_count</h3>
8578<ul>
8579
8580<li>
8581
8582<p>Syntax:</p>
8583
8584<div>
8585<div>
8586<pre class="source">strict_count(collection)
8587</pre></div></div>
8588</li>
8589<li>
8590
8591<p>Gets the number of items in the given collection.</p>
8592</li>
8593<li>Arguments:
8594<ul>
8595
8596<li><tt>collection</tt> could be:
8597<ul>
8598
8599<li>an <tt>array</tt> or <tt>multiset</tt> containing the items to be counted,</li>
8600<li>or a <tt>null</tt> value,</li>
8601<li>or a <tt>missing</tt> value.</li>
8602</ul>
8603</li>
8604</ul>
8605</li>
8606<li>Return Value:
8607<ul>
8608
8609<li>a <tt>bigint</tt> value representing the number of items in the given collection,</li>
8610<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>.</li>
8611</ul>
8612</li>
8613<li>
8614
8615<p>Example:</p>
8616
8617<div>
8618<div>
8619<pre class="source">strict_count( [1, 2, null, missing] );
8620</pre></div></div>
8621</li>
8622<li>
8623
8624<p>The expected result is:</p>
8625
8626<div>
8627<div>
8628<pre class="source">4
8629</pre></div></div>
8630</li>
8631</ul></div>
8632<div class="section">
8633<h3><a name="strict_avg"></a>strict_avg</h3>
8634<ul>
8635
8636<li>
8637
8638<p>Syntax:</p>
8639
8640<div>
8641<div>
8642<pre class="source">strict_avg(num_collection)
8643</pre></div></div>
8644</li>
8645<li>
8646
8647<p>Gets the average value of the numeric items in the given collection.</p>
8648</li>
8649<li>Arguments:
8650<ul>
8651
8652<li><tt>num_collection</tt> could be:
8653<ul>
8654
8655<li>an <tt>array</tt> or <tt>multiset</tt> containing numeric values, <tt>null</tt>s or <tt>missing</tt>s,</li>
8656<li>or, a <tt>null</tt> value,</li>
8657<li>or, a <tt>missing</tt> value.</li>
8658</ul>
8659</li>
8660</ul>
8661</li>
8662<li>Return Value:
8663<ul>
8664
8665<li>a <tt>double</tt> value representing the average of the numbers in the given collection,</li>
8666<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
8667<li><tt>null</tt> is returned if there is a <tt>null</tt> or <tt>missing</tt> in the input collection,</li>
8668<li>any other non-numeric value in the input collection will cause a type error.</li>
8669</ul>
8670</li>
8671<li>
8672
8673<p>Example:</p>
8674
8675<div>
8676<div>
8677<pre class="source">strict_avg( [100, 200, 300] );
8678</pre></div></div>
8679</li>
8680<li>
8681
8682<p>The expected result is:</p>
8683
8684<div>
8685<div>
8686<pre class="source">200.0
8687</pre></div></div>
8688</li>
8689</ul></div>
8690<div class="section">
8691<h3><a name="strict_sum"></a>strict_sum</h3>
8692<ul>
8693
8694<li>
8695
8696<p>Syntax:</p>
8697
8698<div>
8699<div>
8700<pre class="source">strict_sum(num_collection)
8701</pre></div></div>
8702</li>
8703<li>
8704
8705<p>Gets the sum of the items in the given collection.</p>
8706</li>
8707<li>Arguments:
8708<ul>
8709
8710<li><tt>num_collection</tt> could be:
8711<ul>
8712
8713<li>an <tt>array</tt> or <tt>multiset</tt> containing numeric values, <tt>null</tt>s or <tt>missing</tt>s,</li>
8714<li>or, a <tt>null</tt> value,</li>
8715<li>or, a <tt>missing</tt> value.</li>
8716</ul>
8717</li>
8718</ul>
8719</li>
8720<li>Return Value:
8721<ul>
8722
8723<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>
8724<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
8725<li><tt>null</tt> is returned if there is a <tt>null</tt> or <tt>missing</tt> in the input collection,</li>
8726<li>any other non-numeric value in the input collection will cause a type error.</li>
8727</ul>
8728</li>
8729<li>
8730
8731<p>Example:</p>
8732
8733<div>
8734<div>
8735<pre class="source">strict_sum( [100, 200, 300] );
8736</pre></div></div>
8737</li>
8738<li>
8739
8740<p>The expected result is:</p>
8741
8742<div>
8743<div>
8744<pre class="source">600
8745</pre></div></div>
8746</li>
8747</ul></div>
8748<div class="section">
8749<h3><a name="strict_min"></a>strict_min</h3>
8750<ul>
8751
8752<li>
8753
8754<p>Syntax:</p>
8755
8756<div>
8757<div>
8758<pre class="source">strict_min(num_collection)
8759</pre></div></div>
8760</li>
8761<li>
8762
8763<p>Gets the min value of comparable items in the given collection.</p>
8764</li>
8765<li>Arguments:
8766<ul>
8767
8768<li><tt>num_collection</tt> could be:
8769<ul>
8770
8771<li>an <tt>array</tt> or <tt>multiset</tt>,</li>
8772<li>or, a <tt>null</tt> value,</li>
8773<li>or, a <tt>missing</tt> value.</li>
8774</ul>
8775</li>
8776</ul>
8777</li>
8778<li>Return Value:
8779<ul>
8780
8781<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>
8782<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
8783<li><tt>null</tt> is returned if there is a <tt>null</tt> or <tt>missing</tt> in the input collection,</li>
8784<li>multiple incomparable items in the input array or multiset will cause a type error,</li>
8785<li>any other non-array and non-multiset input value will cause a type error.</li>
8786</ul>
8787</li>
8788<li>
8789
8790<p>Example:</p>
8791
8792<div>
8793<div>
8794<pre class="source">strict_min( [10.2, 100, 5] );
8795</pre></div></div>
8796</li>
8797<li>
8798
8799<p>The expected result is:</p>
8800
8801<div>
8802<div>
8803<pre class="source">5.0
8804</pre></div></div>
8805</li>
8806</ul></div>
8807<div class="section">
8808<h3><a name="strict_max"></a>strict_max</h3>
8809<ul>
8810
8811<li>
8812
8813<p>Syntax:</p>
8814
8815<div>
8816<div>
8817<pre class="source">strict_max(num_collection)
8818</pre></div></div>
8819</li>
8820<li>
8821
8822<p>Gets the max value of numeric items in the given collection.</p>
8823</li>
8824<li>Arguments:
8825<ul>
8826
8827<li><tt>num_collection</tt> could be:
8828<ul>
8829
8830<li>an <tt>array</tt> or <tt>multiset</tt>,</li>
8831<li>or, a <tt>null</tt> value,</li>
8832<li>or, a <tt>missing</tt> value.</li>
8833</ul>
8834</li>
8835</ul>
8836</li>
8837<li>Return Value:
8838<ul>
8839
8840<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>
8841<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
8842<li><tt>null</tt> is returned if there is a <tt>null</tt> or <tt>missing</tt> in the input collection,</li>
8843<li>multiple incomparable items in the input array or multiset will cause a type error,</li>
8844<li>any other non-array and non-multiset input value will cause a type error.</li>
8845</ul>
8846</li>
8847<li>
8848
8849<p>Example:</p>
8850
8851<div>
8852<div>
8853<pre class="source">strict_max( [10.2, 100, 5] );
8854</pre></div></div>
8855</li>
8856<li>
8857
8858<p>The expected result is:</p>
8859
8860<div>
8861<div>
8862<pre class="source">100.0
8863</pre></div></div>
8864</li>
8865</ul></div>
8866<div class="section">
8867<h3><a name="strict_stddev_samp"></a>strict_stddev_samp</h3>
8868<ul>
8869
8870<li>
8871
8872<p>Syntax:</p>
8873
8874<div>
8875<div>
8876<pre class="source">strict_stddev_samp(num_collection)
8877</pre></div></div>
8878</li>
8879<li>
8880
8881<p>Gets the sample standard deviation value of the numeric items in the given collection.</p>
8882</li>
8883<li>Arguments:
8884<ul>
8885
8886<li><tt>num_collection</tt> could be:
8887<ul>
8888
8889<li>an <tt>array</tt> or <tt>multiset</tt> containing numeric values, <tt>null</tt>s or <tt>missing</tt>s,</li>
8890<li>or, a <tt>null</tt> value,</li>
8891<li>or, a <tt>missing</tt> value.</li>
8892</ul>
8893</li>
8894</ul>
8895</li>
8896<li>Return Value:
8897<ul>
8898
8899<li>a <tt>double</tt> value representing the sample standard deviation of the numbers in the given collection,</li>
8900<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
8901<li><tt>null</tt> is returned if there is a <tt>null</tt> or <tt>missing</tt> in the input collection,</li>
8902<li>any other non-numeric value in the input collection will cause a type error.</li>
8903</ul>
8904</li>
8905<li>
8906
8907<p>Example:</p>
8908
8909<div>
8910<div>
8911<pre class="source">strict_stddev_samp( [100, 200, 300] );
8912</pre></div></div>
8913</li>
8914<li>
8915
8916<p>The expected result is:</p>
8917
8918<div>
8919<div>
8920<pre class="source">100.0
8921</pre></div></div>
8922</li>
8923</ul></div>
8924<div class="section">
8925<h3><a name="strict_stddev_pop"></a>strict_stddev_pop</h3>
8926<ul>
8927
8928<li>
8929
8930<p>Syntax:</p>
8931
8932<div>
8933<div>
8934<pre class="source">strict_stddev_pop(num_collection)
8935</pre></div></div>
8936</li>
8937<li>
8938
8939<p>Gets the population standard deviation value of the numeric items in the given collection.</p>
8940</li>
8941<li>Arguments:
8942<ul>
8943
8944<li><tt>num_collection</tt> could be:
8945<ul>
8946
8947<li>an <tt>array</tt> or <tt>multiset</tt> containing numeric values, <tt>null</tt>s or <tt>missing</tt>s,</li>
8948<li>or, a <tt>null</tt> value,</li>
8949<li>or, a <tt>missing</tt> value.</li>
8950</ul>
8951</li>
8952</ul>
8953</li>
8954<li>Return Value:
8955<ul>
8956
8957<li>a <tt>double</tt> value representing the population standard deviation of the numbers in the given collection,</li>
8958<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
8959<li><tt>null</tt> is returned if there is a <tt>null</tt> or <tt>missing</tt> in the input collection,</li>
8960<li>any other non-numeric value in the input collection will cause a type error.</li>
8961</ul>
8962</li>
8963<li>
8964
8965<p>Example:</p>
8966
8967<div>
8968<div>
8969<pre class="source">strict_stddev_pop( [100, 200, 300] );
8970</pre></div></div>
8971</li>
8972<li>
8973
8974<p>The expected result is:</p>
8975
8976<div>
8977<div>
8978<pre class="source">81.64965809277261
8979</pre></div></div>
8980</li>
8981</ul></div>
8982<div class="section">
8983<h3><a name="strict_var_samp"></a>strict_var_samp</h3>
8984<ul>
8985
8986<li>
8987
8988<p>Syntax:</p>
8989
8990<div>
8991<div>
8992<pre class="source">strict_var_samp(num_collection)
8993</pre></div></div>
8994</li>
8995<li>
8996
8997<p>Gets the sample variance value of the numeric items in the given collection.</p>
8998</li>
8999<li>Arguments:
9000<ul>
9001
9002<li><tt>num_collection</tt> could be:
9003<ul>
9004
9005<li>an <tt>array</tt> or <tt>multiset</tt> containing numeric values, <tt>null</tt>s or <tt>missing</tt>s,</li>
9006<li>or, a <tt>null</tt> value,</li>
9007<li>or, a <tt>missing</tt> value.</li>
9008</ul>
9009</li>
9010</ul>
9011</li>
9012<li>Return Value:
9013<ul>
9014
9015<li>a <tt>double</tt> value representing the sample variance of the numbers in the given collection,</li>
9016<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
9017<li><tt>null</tt> is returned if there is a <tt>null</tt> or <tt>missing</tt> in the input collection,</li>
9018<li>any other non-numeric value in the input collection will cause a type error.</li>
9019</ul>
9020</li>
9021<li>
9022
9023<p>Example:</p>
9024
9025<div>
9026<div>
9027<pre class="source">strict_var_samp( [100, 200, 300] );
9028</pre></div></div>
9029</li>
9030<li>
9031
9032<p>The expected result is:</p>
9033
9034<div>
9035<div>
9036<pre class="source">10000.0
9037</pre></div></div>
9038</li>
9039</ul></div>
9040<div class="section">
9041<h3><a name="strict_var_pop"></a>strict_var_pop</h3>
9042<ul>
9043
9044<li>
9045
9046<p>Syntax:</p>
9047
9048<div>
9049<div>
9050<pre class="source">strict_var_pop(num_collection)
9051</pre></div></div>
9052</li>
9053<li>
9054
9055<p>Gets the population variance value of the numeric items in the given collection.</p>
9056</li>
9057<li>Arguments:
9058<ul>
9059
9060<li><tt>num_collection</tt> could be:
9061<ul>
9062
9063<li>an <tt>array</tt> or <tt>multiset</tt> containing numeric values, <tt>null</tt>s or <tt>missing</tt>s,</li>
9064<li>or, a <tt>null</tt> value,</li>
9065<li>or, a <tt>missing</tt> value.</li>
9066</ul>
9067</li>
9068</ul>
9069</li>
9070<li>Return Value:
9071<ul>
9072
9073<li>a <tt>double</tt> value representing the population variance of the numbers in the given collection,</li>
9074<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
9075<li><tt>null</tt> is returned if there is a <tt>null</tt> or <tt>missing</tt> in the input collection,</li>
9076<li>any other non-numeric value in the input collection will cause a type error.</li>
9077</ul>
9078</li>
9079<li>
9080
9081<p>Example:</p>
9082
9083<div>
9084<div>
9085<pre class="source">strict_var_pop( [100, 200, 300] );
9086</pre></div></div>
9087</li>
9088<li>
9089
9090<p>The expected result is:</p>
9091
9092<div>
9093<div>
9094<pre class="source">6666.666666666667
9095</pre></div></div>
9096</li>
9097</ul></div>
9098<div class="section">
9099<h3><a name="strict_skewness"></a>strict_skewness</h3>
9100<ul>
9101
9102<li>
9103
9104<p>Syntax:</p>
9105
9106<div>
9107<div>
9108<pre class="source">strict_skewness(num_collection)
9109</pre></div></div>
9110</li>
9111<li>
9112
9113<p>Gets the skewness value of the numeric items in the given collection.</p>
9114</li>
9115<li>Arguments:
9116<ul>
9117
9118<li><tt>num_collection</tt> could be:
9119<ul>
9120
9121<li>an <tt>array</tt> or <tt>multiset</tt> containing numeric values, <tt>null</tt>s or <tt>missing</tt>s,</li>
9122<li>or, a <tt>null</tt> value,</li>
9123<li>or, a <tt>missing</tt> value.</li>
9124</ul>
9125</li>
9126</ul>
9127</li>
9128<li>Return Value:
9129<ul>
9130
9131<li>a <tt>double</tt> value representing the skewness of the numbers in the given collection,</li>
9132<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
9133<li><tt>null</tt> is returned if there is a <tt>null</tt> or <tt>missing</tt> in the input collection,</li>
9134<li>any other non-numeric value in the input collection will cause a type error.</li>
9135</ul>
9136</li>
9137<li>
9138
9139<p>Example:</p>
9140
9141<div>
9142<div>
9143<pre class="source">strict_skewness( [100, 200, 300] );
9144</pre></div></div>
9145</li>
9146<li>
9147
9148<p>The expected result is:</p>
9149
9150<div>
9151<div>
9152<pre class="source">0.0
9153</pre></div></div>
9154</li>
9155</ul></div>
9156<div class="section">
9157<h3><a name="strict_kurtosis"></a>strict_kurtosis</h3>
9158<ul>
9159
9160<li>
9161
9162<p>Syntax:</p>
9163
9164<div>
9165<div>
9166<pre class="source">strict_kurtosis(num_collection)
9167</pre></div></div>
9168</li>
9169<li>
9170
9171<p>Gets the kurtosis value from the normal distribution of the numeric items in the given collection.</p>
9172</li>
9173<li>Arguments:
9174<ul>
9175
9176<li><tt>num_collection</tt> could be:
9177<ul>
9178
9179<li>an <tt>array</tt> or <tt>multiset</tt> containing numeric values, <tt>null</tt>s or <tt>missing</tt>s,</li>
9180<li>or, a <tt>null</tt> value,</li>
9181<li>or, a <tt>missing</tt> value.</li>
9182</ul>
9183</li>
9184</ul>
9185</li>
9186<li>Return Value:
9187<ul>
9188
9189<li>a <tt>double</tt> value representing the kurtosis from a normal distribution of the numbers in the given collection,</li>
9190<li><tt>null</tt> is returned if the input is <tt>null</tt> or <tt>missing</tt>,</li>
9191<li><tt>null</tt> is returned if there is a <tt>null</tt> or <tt>missing</tt> in the input collection,</li>
9192<li>any other non-numeric value in the input collection will cause a type error.</li>
9193</ul>
9194</li>
9195<li>
9196
9197<p>Example:</p>
9198
9199<div>
9200<div>
9201<pre class="source">strict_kurtosis( [100, 200, 300] );
9202</pre></div></div>
9203</li>
9204<li>
9205
9206<p>The expected result is:</p>
9207
9208<div>
9209<div>
9210<pre class="source">-1.5
9211</pre></div></div>
9212</li>
9213</ul><!--
9214 ! Licensed to the Apache Software Foundation (ASF) under one
9215 ! or more contributor license agreements. See the NOTICE file
9216 ! distributed with this work for additional information
9217 ! regarding copyright ownership. The ASF licenses this file
9218 ! to you under the Apache License, Version 2.0 (the
9219 ! "License"); you may not use this file except in compliance
9220 ! with the License. You may obtain a copy of the License at
9221 !
9222 ! http://www.apache.org/licenses/LICENSE-2.0
9223 !
9224 ! Unless required by applicable law or agreed to in writing,
9225 ! software distributed under the License is distributed on an
9226 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
9227 ! KIND, either express or implied. See the License for the
9228 ! specific language governing permissions and limitations
9229 ! under the License.
9230 !-->
9231</div></div>
9232<div class="section">
9233<h2><a name="Comparison_Functions"></a><a name="ComparisonFunctions" id="ComparisonFunctions">Comparison Functions</a></h2>
9234<div class="section">
9235<h3><a name="greatest"></a>greatest</h3>
9236<ul>
9237
9238<li>
9239
9240<p>Syntax:</p>
9241
9242<div>
9243<div>
9244<pre class="source">greatest(numeric_value1, numeric_value2, ...)
9245</pre></div></div>
9246</li>
9247<li>
9248
9249<p>Computes the greatest value among arguments.</p>
9250</li>
9251<li>Arguments:
9252<ul>
9253
9254<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>
9255<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>
9256<li>&#x2026;.</li>
9257</ul>
9258</li>
9259<li>Return Value:
9260<ul>
9261
9262<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>
9263<li><tt>null</tt> if any argument is a <tt>missing</tt> value or <tt>null</tt> value,</li>
9264<li>any other non-numeric input value will cause a type error.</li>
9265</ul>
9266</li>
9267<li>
9268
9269<p>Example:</p>
9270
9271<div>
9272<div>
9273<pre class="source">{ &quot;v1&quot;: greatest(1, 2, 3), &quot;v2&quot;: greatest(float(&quot;0.5&quot;), double(&quot;-0.5&quot;), 5000) };
9274</pre></div></div>
9275</li>
9276<li>
9277
9278<p>The expected result is:</p>
9279
9280<div>
9281<div>
9282<pre class="source">{ &quot;v1&quot;: 3, &quot;v2&quot;: 5000.0 }
9283</pre></div></div>
9284</li>
9285</ul></div>
9286<div class="section">
9287<h3><a name="least"></a>least</h3>
9288<ul>
9289
9290<li>
9291
9292<p>Syntax:</p>
9293
9294<div>
9295<div>
9296<pre class="source">least(numeric_value1, numeric_value2, ...)
9297</pre></div></div>
9298</li>
9299<li>
9300
9301<p>Computes the least value among arguments.</p>
9302</li>
9303<li>Arguments:
9304<ul>
9305
9306<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>
9307<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>
9308<li>&#x2026;.</li>
9309</ul>
9310</li>
9311<li>Return Value:
9312<ul>
9313
9314<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>
9315<li><tt>null</tt> if any argument is a <tt>missing</tt> value or <tt>null</tt> value,</li>
9316<li>any other non-numeric input value will cause a type error.</li>
9317</ul>
9318</li>
9319<li>
9320
9321<p>Example:</p>
9322
9323<div>
9324<div>
9325<pre class="source">{ &quot;v1&quot;: least(1, 2, 3), &quot;v2&quot;: least(float(&quot;0.5&quot;), double(&quot;-0.5&quot;), 5000) };
9326</pre></div></div>
9327</li>
9328<li>
9329
9330<p>The expected result is:</p>
9331
9332<div>
9333<div>
9334<pre class="source">{ &quot;v1&quot;: 1, &quot;v2&quot;: -0.5 }
9335</pre></div></div>
9336</li>
9337</ul><!--
9338 ! Licensed to the Apache Software Foundation (ASF) under one
9339 ! or more contributor license agreements. See the NOTICE file
9340 ! distributed with this work for additional information
9341 ! regarding copyright ownership. The ASF licenses this file
9342 ! to you under the Apache License, Version 2.0 (the
9343 ! "License"); you may not use this file except in compliance
9344 ! with the License. You may obtain a copy of the License at
9345 !
9346 ! http://www.apache.org/licenses/LICENSE-2.0
9347 !
9348 ! Unless required by applicable law or agreed to in writing,
9349 ! software distributed under the License is distributed on an
9350 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
9351 ! KIND, either express or implied. See the License for the
9352 ! specific language governing permissions and limitations
9353 ! under the License.
9354 !-->
9355</div></div>
9356<div class="section">
9357<h2><a name="Type_Functions"></a><a name="TypeFunctions" id="TypeFunctions">Type Functions</a></h2>
9358<div class="section">
9359<h3><a name="is_array"></a>is_array</h3>
9360<ul>
9361
9362<li>
9363
9364<p>Syntax:</p>
9365
9366<div>
9367<div>
9368<pre class="source">is_array(expr)
9369</pre></div></div>
9370</li>
9371<li>
9372
9373<p>Checks whether the given expression is evaluated to be an <tt>array</tt> value.</p>
9374</li>
9375<li>Arguments:
9376<ul>
9377
9378<li><tt>expr</tt> : an expression (any type is allowed).</li>
9379</ul>
9380</li>
9381<li>Return Value:
9382<ul>
9383
9384<li>a <tt>boolean</tt> on whether the argument is an <tt>array</tt> value or not,</li>
9385<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
9386<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
9387</ul>
9388</li>
9389<li>
9390
9391<p>Example:</p>
9392
9393<div>
9394<div>
9395<pre class="source">{
9396 &quot;a&quot;: is_array(true),
9397 &quot;b&quot;: is_array(false),
9398 &quot;c&quot;: isarray(null),
9399 &quot;d&quot;: isarray(missing),
9400 &quot;e&quot;: isarray(&quot;d&quot;),
9401 &quot;f&quot;: isarray(4.0),
9402 &quot;g&quot;: isarray(5),
9403 &quot;h&quot;: isarray([&quot;1&quot;, 2]),
9404 &quot;i&quot;: isarray({&quot;a&quot;:1})
9405};
9406</pre></div></div>
9407</li>
9408<li>
9409
9410<p>The expected result is:</p>
9411
9412<div>
9413<div>
9414<pre class="source">{ &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 }
9415</pre></div></div>
9416</li>
9417</ul>
9418<p>The function has an alias <tt>isarray</tt>.</p></div>
9419<div class="section">
9420<h3><a name="is_multiset"></a>is_multiset</h3>
9421<ul>
9422
9423<li>
9424
9425<p>Syntax:</p>
9426
9427<div>
9428<div>
9429<pre class="source">is_multiset(expr)
9430</pre></div></div>
9431</li>
9432<li>
9433
9434<p>Checks whether the given expression is evaluated to be an <tt>multiset</tt> value.</p>
9435</li>
9436<li>Arguments:
9437<ul>
9438
9439<li><tt>expr</tt> : an expression (any type is allowed).</li>
9440</ul>
9441</li>
9442<li>Return Value:
9443<ul>
9444
9445<li>a <tt>boolean</tt> on whether the argument is an <tt>multiset</tt> value or not,</li>
9446<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
9447<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
9448</ul>
9449</li>
9450<li>
9451
9452<p>Example:</p>
9453
9454<div>
9455<div>
9456<pre class="source">{
9457 &quot;a&quot;: is_multiset(true),
9458 &quot;b&quot;: is_multiset(false),
9459 &quot;c&quot;: is_multiset(null),
9460 &quot;d&quot;: is_multiset(missing),
9461 &quot;e&quot;: is_multiset(&quot;d&quot;),
9462 &quot;f&quot;: ismultiset(4.0),
9463 &quot;g&quot;: ismultiset([&quot;1&quot;, 2]),
9464 &quot;h&quot;: ismultiset({&quot;a&quot;:1}),
9465 &quot;i&quot;: ismultiset({{&quot;hello&quot;, 9328, &quot;world&quot;, [1, 2, null]}})
9466};
9467</pre></div></div>
9468</li>
9469<li>
9470
9471<p>The expected result is:</p>
9472
9473<div>
9474<div>
9475<pre class="source">{ &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;: false, &quot;i&quot;: true }
9476</pre></div></div>
9477</li>
9478</ul>
9479<p>The function has an alias <tt>ismultiset</tt>.</p></div>
9480<div class="section">
9481<h3><a name="is_atomic_.28is_atom.29"></a>is_atomic (is_atom)</h3>
9482<ul>
9483
9484<li>
9485
9486<p>Syntax:</p>
9487
9488<div>
9489<div>
9490<pre class="source">is_atomic(expr)
9491</pre></div></div>
9492</li>
9493<li>
9494
9495<p>Checks whether the given expression is evaluated to be a value of a <a href="../datamodel.html#PrimitiveTypes">primitive</a> type.</p>
9496</li>
9497<li>Arguments:
9498<ul>
9499
9500<li><tt>expr</tt> : an expression (any type is allowed).</li>
9501</ul>
9502</li>
9503<li>Return Value:
9504<ul>
9505
9506<li>a <tt>boolean</tt> on whether the argument is a primitive type or not,</li>
9507<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
9508<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
9509</ul>
9510</li>
9511<li>
9512
9513<p>Example:</p>
9514
9515<div>
9516<div>
9517<pre class="source">{
9518 &quot;a&quot;: is_atomic(true),
9519 &quot;b&quot;: is_atomic(false),
9520 &quot;c&quot;: isatomic(null),
9521 &quot;d&quot;: isatomic(missing),
9522 &quot;e&quot;: isatomic(&quot;d&quot;),
9523 &quot;f&quot;: isatom(4.0),
9524 &quot;g&quot;: isatom(5),
9525 &quot;h&quot;: isatom([&quot;1&quot;, 2]),
9526 &quot;i&quot;: isatom({&quot;a&quot;:1})
9527};
9528</pre></div></div>
9529</li>
9530<li>
9531
9532<p>The expected result is:</p>
9533
9534<div>
9535<div>
9536<pre class="source">{ &quot;a&quot;: true, &quot;b&quot;: true, &quot;c&quot;: null, &quot;e&quot;: true, &quot;f&quot;: true, &quot;g&quot;: true, &quot;h&quot;: false, &quot;i&quot;: false }
9537</pre></div></div>
9538</li>
9539</ul>
9540<p>The function has three aliases: <tt>isatomic</tt>, <tt>is_atom</tt>, and <tt>isatom</tt>.</p></div>
9541<div class="section">
9542<h3><a name="is_boolean_.28is_bool.29"></a>is_boolean (is_bool)</h3>
9543<ul>
9544
9545<li>
9546
9547<p>Syntax:</p>
9548
9549<div>
9550<div>
9551<pre class="source">is_boolean(expr)
9552</pre></div></div>
9553</li>
9554<li>
9555
9556<p>Checks whether the given expression is evaluated to be a <tt>boolean</tt> value.</p>
9557</li>
9558<li>Arguments:
9559<ul>
9560
9561<li><tt>expr</tt> : an expression (any type is allowed).</li>
9562</ul>
9563</li>
9564<li>Return Value:
9565<ul>
9566
9567<li>a <tt>boolean</tt> on whether the argument is a <tt>boolean</tt> value or not,</li>
9568<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
9569<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
9570</ul>
9571</li>
9572<li>
9573
9574<p>Example:</p>
9575
9576<div>
9577<div>
9578<pre class="source">{
9579 &quot;a&quot;: isboolean(true),
9580 &quot;b&quot;: isboolean(false),
9581 &quot;c&quot;: is_boolean(null),
9582 &quot;d&quot;: is_boolean(missing),
9583 &quot;e&quot;: isbool(&quot;d&quot;),
9584 &quot;f&quot;: isbool(4.0),
9585 &quot;g&quot;: isbool(5),
9586 &quot;h&quot;: isbool([&quot;1&quot;, 2]),
9587 &quot;i&quot;: isbool({&quot;a&quot;:1})
9588};
9589</pre></div></div>
9590</li>
9591<li>
9592
9593<p>The expected result is:</p>
9594
9595<div>
9596<div>
9597<pre class="source">{ &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 }
9598</pre></div></div>
9599</li>
9600</ul>
9601<p>The function has three aliases: <tt>isboolean</tt>, <tt>is_bool</tt>, and <tt>isbool</tt>.</p></div>
9602<div class="section">
9603<h3><a name="is_number_.28is_num.29"></a>is_number (is_num)</h3>
9604<ul>
9605
9606<li>
9607
9608<p>Syntax:</p>
9609
9610<div>
9611<div>
9612<pre class="source">is_number(expr)
9613</pre></div></div>
9614</li>
9615<li>
9616
9617<p>Checks whether the given expression is evaluated to be a numeric value.</p>
9618</li>
9619<li>Arguments:
9620<ul>
9621
9622<li><tt>expr</tt> : an expression (any type is allowed).</li>
9623</ul>
9624</li>
9625<li>Return Value:
9626<ul>
9627
9628<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>
9629<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
9630<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
9631</ul>
9632</li>
9633<li>
9634
9635<p>Example:</p>
9636
9637<div>
9638<div>
9639<pre class="source">{
9640 &quot;a&quot;: is_number(true),
9641 &quot;b&quot;: is_number(false),
9642 &quot;c&quot;: isnumber(null),
9643 &quot;d&quot;: isnumber(missing),
9644 &quot;e&quot;: isnumber(&quot;d&quot;),
9645 &quot;f&quot;: isnum(4.0),
9646 &quot;g&quot;: isnum(5),
9647 &quot;h&quot;: isnum([&quot;1&quot;, 2]),
9648 &quot;i&quot;: isnum({&quot;a&quot;:1})
9649};
9650</pre></div></div>
9651</li>
9652<li>
9653
9654<p>The expected result is:</p>
9655
9656<div>
9657<div>
9658<pre class="source">{ &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 }
9659</pre></div></div>
9660</li>
9661</ul>
9662<p>The function has three aliases: <tt>isnumber</tt>, <tt>is_num</tt>, and <tt>isnum</tt>.</p></div>
9663<div class="section">
9664<h3><a name="is_object_.28is_obj.29"></a>is_object (is_obj)</h3>
9665<ul>
9666
9667<li>
9668
9669<p>Syntax:</p>
9670
9671<div>
9672<div>
9673<pre class="source">is_object(expr)
9674</pre></div></div>
9675</li>
9676<li>
9677
9678<p>Checks whether the given expression is evaluated to be a <tt>object</tt> value.</p>
9679</li>
9680<li>Arguments:
9681<ul>
9682
9683<li><tt>expr</tt> : an expression (any type is allowed).</li>
9684</ul>
9685</li>
9686<li>Return Value:
9687<ul>
9688
9689<li>a <tt>boolean</tt> on whether the argument is a <tt>object</tt> value or not,</li>
9690<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
9691<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
9692</ul>
9693</li>
9694<li>
9695
9696<p>Example:</p>
9697
9698<div>
9699<div>
9700<pre class="source">{
9701 &quot;a&quot;: is_object(true),
9702 &quot;b&quot;: is_object(false),
9703 &quot;c&quot;: isobject(null),
9704 &quot;d&quot;: isobject(missing),
9705 &quot;e&quot;: isobj(&quot;d&quot;),
9706 &quot;f&quot;: isobj(4.0),
9707 &quot;g&quot;: isobj(5),
9708 &quot;h&quot;: isobj([&quot;1&quot;, 2]),
9709 &quot;i&quot;: isobj({&quot;a&quot;:1})
9710};
9711</pre></div></div>
9712</li>
9713<li>
9714
9715<p>The expected result is:</p>
9716<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>
9717</li>
9718</ul>
9719<p>The function has three aliases: <tt>isobject</tt>, <tt>is_obj</tt>, and <tt>isobj</tt>.</p></div>
9720<div class="section">
9721<h3><a name="is_string_.28is_str.29"></a>is_string (is_str)</h3>
9722<ul>
9723
9724<li>
9725
9726<p>Syntax:</p>
9727
9728<div>
9729<div>
9730<pre class="source">is_string(expr)
9731</pre></div></div>
9732</li>
9733<li>
9734
9735<p>Checks whether the given expression is evaluated to be a <tt>string</tt> value.</p>
9736</li>
9737<li>Arguments:
9738<ul>
9739
9740<li><tt>expr</tt> : an expression (any type is allowed).</li>
9741</ul>
9742</li>
9743<li>Return Value:
9744<ul>
9745
9746<li>a <tt>boolean</tt> on whether the argument is a <tt>string</tt> value or not,</li>
9747<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
9748<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
9749</ul>
9750</li>
9751<li>
9752
9753<p>Example:</p>
9754
9755<div>
9756<div>
9757<pre class="source">{
9758 &quot;a&quot;: is_string(true),
9759 &quot;b&quot;: isstring(false),
9760 &quot;c&quot;: isstring(null),
9761 &quot;d&quot;: isstr(missing),
9762 &quot;e&quot;: isstr(&quot;d&quot;),
9763 &quot;f&quot;: isstr(4.0),
9764 &quot;g&quot;: isstr(5),
9765 &quot;h&quot;: isstr([&quot;1&quot;, 2]),
9766 &quot;i&quot;: isstr({&quot;a&quot;:1})
9767};
9768</pre></div></div>
9769</li>
9770<li>
9771
9772<p>The expected result is:</p>
9773
9774<div>
9775<div>
9776<pre class="source">{ &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 }
9777</pre></div></div>
9778</li>
9779</ul>
9780<p>The function has three aliases: <tt>isstring</tt>, <tt>is_str</tt>, and <tt>isstr</tt>.</p></div>
9781<div class="section">
9782<h3><a name="is_null"></a>is_null</h3>
9783<ul>
9784
9785<li>
9786
9787<p>Syntax:</p>
9788
9789<div>
9790<div>
9791<pre class="source">is_null(expr)
9792</pre></div></div>
9793</li>
9794<li>
9795
9796<p>Checks whether the given expression is evaluated to be a <tt>null</tt> value.</p>
9797</li>
9798<li>Arguments:
9799<ul>
9800
9801<li><tt>expr</tt> : an expression (any type is allowed).</li>
9802</ul>
9803</li>
9804<li>Return Value:
9805<ul>
9806
9807<li>a <tt>boolean</tt> on whether the variable is a <tt>null</tt> or not,</li>
9808<li>a <tt>missing</tt> if the input is <tt>missing</tt>.</li>
9809</ul>
9810</li>
9811<li>
9812
9813<p>Example:</p>
9814
9815<div>
9816<div>
9817<pre class="source">{ &quot;v1&quot;: is_null(null), &quot;v2&quot;: is_null(1), &quot;v3&quot;: is_null(missing) };
9818</pre></div></div>
9819</li>
9820<li>
9821
9822<p>The expected result is:</p>
9823
9824<div>
9825<div>
9826<pre class="source">{ &quot;v1&quot;: true, &quot;v2&quot;: false }
9827</pre></div></div>
9828</li>
9829</ul>
9830<p>The function has an alias <tt>isnull</tt>.</p></div>
9831<div class="section">
9832<h3><a name="is_missing"></a>is_missing</h3>
9833<ul>
9834
9835<li>
9836
9837<p>Syntax:</p>
9838
9839<div>
9840<div>
9841<pre class="source">is_missing(expr)
9842</pre></div></div>
9843</li>
9844<li>
9845
9846<p>Checks whether the given expression is evaluated to be a <tt>missing</tt> value.</p>
9847</li>
9848<li>Arguments:
9849<ul>
9850
9851<li><tt>expr</tt> : an expression (any type is allowed).</li>
9852</ul>
9853</li>
9854<li>Return Value:
9855<ul>
9856
9857<li>a <tt>boolean</tt> on whether the variable is a <tt>missing</tt> or not.</li>
9858</ul>
9859</li>
9860<li>
9861
9862<p>Example:</p>
9863
9864<div>
9865<div>
9866<pre class="source">{ &quot;v1&quot;: is_missing(null), &quot;v2&quot;: is_missing(1), &quot;v3&quot;: is_missing(missing) };
9867</pre></div></div>
9868</li>
9869<li>
9870
9871<p>The expected result is:</p>
9872
9873<div>
9874<div>
9875<pre class="source">{ &quot;v1&quot;: false, &quot;v2&quot;: false, &quot;v3&quot;: true }
9876</pre></div></div>
9877</li>
9878</ul>
9879<p>The function has an alias <tt>ismissing</tt>.</p></div>
9880<div class="section">
9881<h3><a name="is_unknown"></a>is_unknown</h3>
9882<ul>
9883
9884<li>
9885
9886<p>Syntax:</p>
9887
9888<div>
9889<div>
9890<pre class="source">is_unknown(expr)
9891</pre></div></div>
9892</li>
9893<li>
9894
9895<p>Checks whether the given variable is a <tt>null</tt> value or a <tt>missing</tt> value.</p>
9896</li>
9897<li>Arguments:
9898<ul>
9899
9900<li><tt>expr</tt> : an expression (any type is allowed).</li>
9901</ul>
9902</li>
9903<li>Return Value:
9904<ul>
9905
9906<li>a <tt>boolean</tt> on whether the variable is a <tt>null</tt>/``missing<tt>value (</tt>true<tt>) or not (</tt>false`).</li>
9907</ul>
9908</li>
9909<li>
9910
9911<p>Example:</p>
9912
9913<div>
9914<div>
9915<pre class="source">{ &quot;v1&quot;: is_unknown(null), &quot;v2&quot;: is_unknown(1), &quot;v3&quot;: is_unknown(missing) };
9916</pre></div></div>
9917</li>
9918<li>
9919
9920<p>The expected result is:</p>
9921
9922<div>
9923<div>
9924<pre class="source">{ &quot;v1&quot;: true, &quot;v2&quot;: false, &quot;v3&quot;: true }
9925</pre></div></div>
9926</li>
9927</ul>
9928<p>The function has an alias <tt>isunknown</tt>.</p><!--
9929 ! Licensed to the Apache Software Foundation (ASF) under one
9930 ! or more contributor license agreements. See the NOTICE file
9931 ! distributed with this work for additional information
9932 ! regarding copyright ownership. The ASF licenses this file
9933 ! to you under the Apache License, Version 2.0 (the
9934 ! "License"); you may not use this file except in compliance
9935 ! with the License. You may obtain a copy of the License at
9936 !
9937 ! http://www.apache.org/licenses/LICENSE-2.0
9938 !
9939 ! Unless required by applicable law or agreed to in writing,
9940 ! software distributed under the License is distributed on an
9941 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
9942 ! KIND, either express or implied. See the License for the
9943 ! specific language governing permissions and limitations
9944 ! under the License.
9945 !-->
9946</div>
9947<div class="section">
9948<h3><a name="is_binary_.28is_bin.29"></a>is_binary (is_bin)</h3>
9949<ul>
9950
9951<li>
9952
9953<p>Syntax:</p>
9954
9955<div>
9956<div>
9957<pre class="source">is_binary(expr)
9958</pre></div></div>
9959</li>
9960<li>
9961
9962<p>Checks whether the given expression is evaluated to be a <tt>binary</tt> value.</p>
9963</li>
9964<li>Arguments:
9965<ul>
9966
9967<li><tt>expr</tt> : an expression (any type is allowed).</li>
9968</ul>
9969</li>
9970<li>Return Value:
9971<ul>
9972
9973<li>a <tt>boolean</tt> on whether the argument is a <tt>binary</tt> value or not,</li>
9974<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
9975<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
9976</ul>
9977</li>
9978<li>
9979
9980<p>Example:</p>
9981
9982<div>
9983<div>
9984<pre class="source">{
9985 &quot;a&quot;: is_binary(true),
9986 &quot;b&quot;: is_binary(false),
9987 &quot;c&quot;: isbinary(null),
9988 &quot;d&quot;: isbinary(missing),
9989 &quot;e&quot;: isbin(point(&quot;1,2&quot;)),
9990 &quot;f&quot;: isbin(hex(&quot;ABCDEF0123456789&quot;)),
9991 &quot;g&quot;: is_bin(sub_binary(hex(&quot;AABBCCDD&quot;), 4)),
9992 &quot;h&quot;: is_bin(2),
9993 &quot;i&quot;: is_bin({&quot;a&quot;:1})
9994};
9995</pre></div></div>
9996</li>
9997<li>
9998
9999<p>The expected result is:</p>
10000
10001<div>
10002<div>
10003<pre class="source">{ &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 }
10004</pre></div></div>
10005</li>
10006</ul>
10007<p>The function has three aliases: <tt>isbinary</tt>, <tt>is_bin</tt>, and <tt>isbin</tt>.</p></div>
10008<div class="section">
10009<h3><a name="is_uuid"></a>is_uuid</h3>
10010<ul>
10011
10012<li>
10013
10014<p>Syntax:</p>
10015
10016<div>
10017<div>
10018<pre class="source">is_uuid(expr)
10019</pre></div></div>
10020</li>
10021<li>
10022
10023<p>Checks whether the given expression is evaluated to be a <tt>uuid</tt> value.</p>
10024</li>
10025<li>Arguments:
10026<ul>
10027
10028<li><tt>expr</tt> : an expression (any type is allowed).</li>
10029</ul>
10030</li>
10031<li>Return Value:
10032<ul>
10033
10034<li>a <tt>boolean</tt> on whether the argument is a <tt>uuid</tt> value or not,</li>
10035<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
10036<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
10037</ul>
10038</li>
10039<li>
10040
10041<p>Example:</p>
10042
10043<div>
10044<div>
10045<pre class="source"> {
10046 &quot;a&quot;: is_uuid(true),
10047 &quot;b&quot;: is_uuid(false),
10048 &quot;c&quot;: is_uuid(null),
10049 &quot;d&quot;: is_uuid(missing),
10050 &quot;e&quot;: isuuid(4.0),
10051 &quot;f&quot;: isuuid(date(&quot;2013-01-01&quot;)),
10052 &quot;g&quot;: isuuid(uuid(&quot;5c848e5c-6b6a-498f-8452-8847a2957421&quot;))
10053};
10054</pre></div></div>
10055</li>
10056<li>
10057
10058<p>The expected result is:</p>
10059
10060<div>
10061<div>
10062<pre class="source">{ &quot;a&quot;: false, &quot;b&quot;: false, &quot;c&quot;: null, &quot;e&quot;: false, &quot;f&quot;: false, &quot;g&quot;: true }
10063</pre></div></div>
10064</li>
10065</ul>
10066<p>The function has an alias <tt>isuuid</tt>.</p></div>
10067<div class="section">
10068<h3><a name="is_point"></a>is_point</h3>
10069<ul>
10070
10071<li>
10072
10073<p>Syntax:</p>
10074
10075<div>
10076<div>
10077<pre class="source">is_point(expr)
10078</pre></div></div>
10079</li>
10080<li>
10081
10082<p>Checks whether the given expression is evaluated to be a <tt>point</tt> value.</p>
10083</li>
10084<li>Arguments:
10085<ul>
10086
10087<li><tt>expr</tt> : an expression (any type is allowed).</li>
10088</ul>
10089</li>
10090<li>Return Value:
10091<ul>
10092
10093<li>a <tt>boolean</tt> on whether the argument is a <tt>point</tt> value or not,</li>
10094<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
10095<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
10096</ul>
10097</li>
10098<li>
10099
10100<p>Example:</p>
10101
10102<div>
10103<div>
10104<pre class="source">{
10105 &quot;a&quot;: is_point(true),
10106 &quot;b&quot;: is_point(false),
10107 &quot;c&quot;: is_point(null),
10108 &quot;d&quot;: is_point(missing),
10109 &quot;e&quot;: is_point(point(&quot;1,2&quot;)),
10110 &quot;f&quot;: ispoint(line(&quot;30.0,70.0 50.0,90.0&quot;)),
10111 &quot;g&quot;: ispoint(rectangle(&quot;30.0,70.0 50.0,90.0&quot;)),
10112 &quot;h&quot;: ispoint(circle(&quot;30.0,70.0 5.0&quot;)),
10113 &quot;i&quot;: ispoint(polygon(&quot;1.0,1.0 2.0,2.0 3.0,3.0 4.0,4.0&quot;)),
10114 &quot;j&quot;: ispoint(3)
10115};
10116</pre></div></div>
10117</li>
10118<li>
10119
10120<p>The expected result is:</p>
10121
10122<div>
10123<div>
10124<pre class="source">{ &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, &quot;j&quot;: false }
10125</pre></div></div>
10126</li>
10127</ul>
10128<p>The function has an alias <tt>ispoint</tt>.</p></div>
10129<div class="section">
10130<h3><a name="is_line"></a>is_line</h3>
10131<ul>
10132
10133<li>
10134
10135<p>Syntax:</p>
10136
10137<div>
10138<div>
10139<pre class="source">is_line(expr)
10140</pre></div></div>
10141</li>
10142<li>
10143
10144<p>Checks whether the given expression is evaluated to be a <tt>line</tt> value.</p>
10145</li>
10146<li>Arguments:
10147<ul>
10148
10149<li><tt>expr</tt> : an expression (any type is allowed).</li>
10150</ul>
10151</li>
10152<li>Return Value:
10153<ul>
10154
10155<li>a <tt>boolean</tt> on whether the argument is a <tt>line</tt> value or not,</li>
10156<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
10157<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
10158</ul>
10159</li>
10160<li>
10161
10162<p>Example:</p>
10163
10164<div>
10165<div>
10166<pre class="source">{
10167 &quot;a&quot;: is_line(true),
10168 &quot;b&quot;: is_line(false),
10169 &quot;c&quot;: is_line(null),
10170 &quot;d&quot;: is_line(missing),
10171 &quot;e&quot;: is_line(point(&quot;1,2&quot;)),
10172 &quot;f&quot;: isline(line(&quot;30.0,70.0 50.0,90.0&quot;)),
10173 &quot;g&quot;: isline(rectangle(&quot;30.0,70.0 50.0,90.0&quot;)),
10174 &quot;h&quot;: isline(circle(&quot;30.0,70.0 5.0&quot;)),
10175 &quot;i&quot;: isline(polygon(&quot;1.0,1.0 2.0,2.0 3.0,3.0 4.0,4.0&quot;)),
10176 &quot;j&quot;: isline(3)
10177};
10178</pre></div></div>
10179</li>
10180<li>
10181
10182<p>The expected result is:</p>
10183
10184<div>
10185<div>
10186<pre class="source">{ &quot;a&quot;: false, &quot;b&quot;: false, &quot;c&quot;: null, &quot;e&quot;: false, &quot;f&quot;: true, &quot;g&quot;: false, &quot;h&quot;: false, &quot;i&quot;: false, &quot;j&quot;: false }
10187</pre></div></div>
10188</li>
10189</ul>
10190<p>The function has an alias <tt>isline</tt>.</p></div>
10191<div class="section">
10192<h3><a name="is_rectangle"></a>is_rectangle</h3>
10193<ul>
10194
10195<li>
10196
10197<p>Syntax:</p>
10198
10199<div>
10200<div>
10201<pre class="source">is_rectangle(expr)
10202</pre></div></div>
10203</li>
10204<li>
10205
10206<p>Checks whether the given expression is evaluated to be a <tt>rectangle</tt> value.</p>
10207</li>
10208<li>Arguments:
10209<ul>
10210
10211<li><tt>expr</tt> : an expression (any type is allowed).</li>
10212</ul>
10213</li>
10214<li>Return Value:
10215<ul>
10216
10217<li>a <tt>boolean</tt> on whether the argument is a <tt>rectangle</tt> value or not,</li>
10218<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
10219<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
10220</ul>
10221</li>
10222<li>
10223
10224<p>Example:</p>
10225
10226<div>
10227<div>
10228<pre class="source">{
10229 &quot;a&quot;: is_rectangle(true),
10230 &quot;b&quot;: is_rectangle(false),
10231 &quot;c&quot;: is_rectangle(null),
10232 &quot;d&quot;: is_rectangle(missing),
10233 &quot;e&quot;: is_rectangle(point(&quot;1,2&quot;)),
10234 &quot;f&quot;: isrectangle(line(&quot;30.0,70.0 50.0,90.0&quot;)),
10235 &quot;g&quot;: isrectangle(rectangle(&quot;30.0,70.0 50.0,90.0&quot;)),
10236 &quot;h&quot;: isrectangle(circle(&quot;30.0,70.0 5.0&quot;)),
10237 &quot;i&quot;: isrectangle(polygon(&quot;1.0,1.0 2.0,2.0 3.0,3.0 4.0,4.0&quot;)),
10238 &quot;j&quot;: isrectangle(3)
10239};
10240</pre></div></div>
10241</li>
10242<li>
10243
10244<p>The expected result is:</p>
10245
10246<div>
10247<div>
10248<pre class="source">{ &quot;a&quot;: false, &quot;b&quot;: false, &quot;c&quot;: null, &quot;e&quot;: false, &quot;f&quot;: false, &quot;g&quot;: true, &quot;h&quot;: false, &quot;i&quot;: false, &quot;j&quot;: false }
10249</pre></div></div>
10250</li>
10251</ul>
10252<p>The function has an alias <tt>isrectangle</tt>.</p></div>
10253<div class="section">
10254<h3><a name="is_circle"></a>is_circle</h3>
10255<ul>
10256
10257<li>
10258
10259<p>Syntax:</p>
10260
10261<div>
10262<div>
10263<pre class="source">is_circle(expr)
10264</pre></div></div>
10265</li>
10266<li>
10267
10268<p>Checks whether the given expression is evaluated to be a <tt>circle</tt> value.</p>
10269</li>
10270<li>Arguments:
10271<ul>
10272
10273<li><tt>expr</tt> : an expression (any type is allowed).</li>
10274</ul>
10275</li>
10276<li>Return Value:
10277<ul>
10278
10279<li>a <tt>boolean</tt> on whether the argument is a <tt>circle</tt> value or not,</li>
10280<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
10281<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
10282</ul>
10283</li>
10284<li>
10285
10286<p>Example:</p>
10287
10288<div>
10289<div>
10290<pre class="source">{
10291 &quot;a&quot;: is_circle(true),
10292 &quot;b&quot;: is_circle(false),
10293 &quot;c&quot;: is_circle(null),
10294 &quot;d&quot;: is_circle(missing),
10295 &quot;e&quot;: is_circle(point(&quot;1,2&quot;)),
10296 &quot;f&quot;: iscircle(line(&quot;30.0,70.0 50.0,90.0&quot;)),
10297 &quot;g&quot;: iscircle(rectangle(&quot;30.0,70.0 50.0,90.0&quot;)),
10298 &quot;h&quot;: iscircle(circle(&quot;30.0,70.0 5.0&quot;)),
10299 &quot;i&quot;: iscircle(polygon(&quot;1.0,1.0 2.0,2.0 3.0,3.0 4.0,4.0&quot;)),
10300 &quot;j&quot;: iscircle(3)
10301};
10302</pre></div></div>
10303</li>
10304<li>
10305
10306<p>The expected result is:</p>
10307
10308<div>
10309<div>
10310<pre class="source">{ &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, &quot;j&quot;: false }
10311</pre></div></div>
10312</li>
10313</ul>
10314<p>The function has an alias <tt>iscircle</tt>.</p></div>
10315<div class="section">
10316<h3><a name="is_polygon"></a>is_polygon</h3>
10317<ul>
10318
10319<li>
10320
10321<p>Syntax:</p>
10322
10323<div>
10324<div>
10325<pre class="source">is_polygon(expr)
10326</pre></div></div>
10327</li>
10328<li>
10329
10330<p>Checks whether the given expression is evaluated to be a <tt>polygon</tt> value.</p>
10331</li>
10332<li>Arguments:
10333<ul>
10334
10335<li><tt>expr</tt> : an expression (any type is allowed).</li>
10336</ul>
10337</li>
10338<li>Return Value:
10339<ul>
10340
10341<li>a <tt>boolean</tt> on whether the argument is a <tt>polygon</tt> value or not,</li>
10342<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
10343<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
10344</ul>
10345</li>
10346<li>
10347
10348<p>Example:</p>
10349
10350<div>
10351<div>
10352<pre class="source">{
10353 &quot;a&quot;: is_polygon(true),
10354 &quot;b&quot;: is_polygon(false),
10355 &quot;c&quot;: is_polygon(null),
10356 &quot;d&quot;: is_polygon(missing),
10357 &quot;e&quot;: is_polygon(point(&quot;1,2&quot;)),
10358 &quot;f&quot;: ispolygon(line(&quot;30.0,70.0 50.0,90.0&quot;)),
10359 &quot;g&quot;: ispolygon(rectangle(&quot;30.0,70.0 50.0,90.0&quot;)),
10360 &quot;h&quot;: ispolygon(circle(&quot;30.0,70.0 5.0&quot;)),
10361 &quot;i&quot;: ispolygon(polygon(&quot;1.0,1.0 2.0,2.0 3.0,3.0 4.0,4.0&quot;)),
10362 &quot;j&quot;: ispolygon(3)
10363};
10364</pre></div></div>
10365</li>
10366<li>
10367
10368<p>The expected result is:</p>
10369
10370<div>
10371<div>
10372<pre class="source">{ &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;: false, &quot;i&quot;: true, &quot;j&quot;: false }
10373</pre></div></div>
10374</li>
10375</ul>
10376<p>The function has an alias <tt>ispolygon</tt>.</p></div>
10377<div class="section">
10378<h3><a name="is_spatial"></a>is_spatial</h3>
10379<ul>
10380
10381<li>
10382
10383<p>Syntax:</p>
10384
10385<div>
10386<div>
10387<pre class="source">is_spatial(expr)
10388</pre></div></div>
10389</li>
10390<li>
10391
10392<p>Checks whether the given expression is evaluated to be a spatial value.</p>
10393</li>
10394<li>Arguments:
10395<ul>
10396
10397<li><tt>expr</tt> : an expression (any type is allowed).</li>
10398</ul>
10399</li>
10400<li>Return Value:
10401<ul>
10402
10403<li>a <tt>boolean</tt> on whether the argument is a <tt>point</tt>/<tt>line</tt>/<tt>rectangle</tt>/<tt>circle</tt>/<tt>polygon</tt> value or not,</li>
10404<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
10405<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
10406</ul>
10407</li>
10408<li>
10409
10410<p>Example:</p>
10411
10412<div>
10413<div>
10414<pre class="source">{
10415 &quot;a&quot;: is_spatial(true),
10416 &quot;b&quot;: is_spatial(false),
10417 &quot;c&quot;: is_spatial(null),
10418 &quot;d&quot;: is_spatial(missing),
10419 &quot;e&quot;: is_spatial(point(&quot;1,2&quot;)),
10420 &quot;f&quot;: isspatial(line(&quot;30.0,70.0 50.0,90.0&quot;)),
10421 &quot;g&quot;: isspatial(rectangle(&quot;30.0,70.0 50.0,90.0&quot;)),
10422 &quot;h&quot;: isspatial(circle(&quot;30.0,70.0 5.0&quot;)),
10423 &quot;i&quot;: isspatial(polygon(&quot;1.0,1.0 2.0,2.0 3.0,3.0 4.0,4.0&quot;)),
10424 &quot;j&quot;: isspatial(3)
10425};
10426</pre></div></div>
10427</li>
10428<li>
10429
10430<p>The expected result is:</p>
10431
10432<div>
10433<div>
10434<pre class="source">{ &quot;a&quot;: false, &quot;b&quot;: false, &quot;c&quot;: null, &quot;e&quot;: true, &quot;f&quot;: true, &quot;g&quot;: true, &quot;h&quot;: true, &quot;i&quot;: true, &quot;j&quot;: false }
10435</pre></div></div>
10436</li>
10437</ul>
10438<p>The function has an alias <tt>isspatial</tt>.</p></div>
10439<div class="section">
10440<h3><a name="is_date"></a>is_date</h3>
10441<ul>
10442
10443<li>
10444
10445<p>Syntax:</p>
10446
10447<div>
10448<div>
10449<pre class="source">is_date(expr)
10450</pre></div></div>
10451</li>
10452<li>
10453
10454<p>Checks whether the given expression is evaluated to be a <tt>date</tt> value.</p>
10455</li>
10456<li>Arguments:
10457<ul>
10458
10459<li><tt>expr</tt> : an expression (any type is allowed).</li>
10460</ul>
10461</li>
10462<li>Return Value:
10463<ul>
10464
10465<li>a <tt>boolean</tt> on whether the argument is a <tt>date</tt> value or not,</li>
10466<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
10467<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
10468</ul>
10469</li>
10470<li>
10471
10472<p>Example:</p>
10473
10474<div>
10475<div>
10476<pre class="source">{
10477 &quot;a&quot;: is_date(true),
10478 &quot;b&quot;: is_date(false),
10479 &quot;c&quot;: is_date(null),
10480 &quot;d&quot;: is_date(missing),
10481 &quot;e&quot;: is_date(date(&quot;-19700101&quot;)),
10482 &quot;f&quot;: isdate(date(&quot;2013-01-01&quot;)),
10483 &quot;g&quot;: isdate(time(&quot;12:12:12.039Z&quot;)),
10484 &quot;h&quot;: isdate(datetime(&quot;2013-01-01T12:12:12.039Z&quot;)),
10485 &quot;i&quot;: isdate(duration(&quot;P100Y12MT12M&quot;)),
10486 &quot;j&quot;: isdate(interval(date(&quot;2013-01-01&quot;), date(&quot;20130505&quot;))),
10487 &quot;k&quot;: isdate(3)
10488};
10489</pre></div></div>
10490</li>
10491<li>
10492
10493<p>The expected result is:</p>
10494
10495<div>
10496<div>
10497<pre class="source">{ &quot;a&quot;: false, &quot;b&quot;: false, &quot;c&quot;: null, &quot;e&quot;: true, &quot;f&quot;: true, &quot;g&quot;: false, &quot;h&quot;: false, &quot;i&quot;: false, &quot;j&quot;: false, &quot;k&quot;: false }
10498</pre></div></div>
10499</li>
10500</ul>
10501<p>The function has an alias <tt>isdate</tt>.</p></div>
10502<div class="section">
10503<h3><a name="is_datetime_.28is_timestamp.29"></a>is_datetime (is_timestamp)</h3>
10504<ul>
10505
10506<li>
10507
10508<p>Syntax:</p>
10509
10510<div>
10511<div>
10512<pre class="source">is_datetime(expr)
10513</pre></div></div>
10514</li>
10515<li>
10516
10517<p>Checks whether the given expression is evaluated to be a <tt>datetime</tt> value.</p>
10518</li>
10519<li>Arguments:
10520<ul>
10521
10522<li><tt>expr</tt> : an expression (any type is allowed).</li>
10523</ul>
10524</li>
10525<li>Return Value:
10526<ul>
10527
10528<li>a <tt>boolean</tt> on whether the argument is a <tt>datetime</tt> value or not,</li>
10529<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
10530<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
10531</ul>
10532</li>
10533<li>
10534
10535<p>Example:</p>
10536
10537<div>
10538<div>
10539<pre class="source">{
10540 &quot;a&quot;: is_datetime(true),
10541 &quot;b&quot;: is_datetime(false),
10542 &quot;c&quot;: is_datetime(null),
10543 &quot;d&quot;: is_datetime(missing),
10544 &quot;e&quot;: is_datetime(datetime(&quot;2016-02-02T12:09:22.023Z&quot;)),
10545 &quot;f&quot;: isdatetime(datetime(&quot;2011-03-03T12:10:42.011Z&quot;)),
10546 &quot;g&quot;: isdatetime(time(&quot;12:12:12.039Z&quot;)),
10547 &quot;h&quot;: is_timestamp(datetime(&quot;2013-01-01T12:12:12.039Z&quot;)),
10548 &quot;i&quot;: is_timestamp(duration(&quot;P100Y12MT12M&quot;)),
10549 &quot;j&quot;: istimestamp(interval(date(&quot;2013-01-01&quot;), date(&quot;20130505&quot;))),
10550 &quot;k&quot;: istimestamp(3)
10551};
10552</pre></div></div>
10553</li>
10554<li>
10555
10556<p>The expected result is:</p>
10557
10558<div>
10559<div>
10560<pre class="source">{ &quot;a&quot;: false, &quot;b&quot;: false, &quot;c&quot;: null, &quot;e&quot;: true, &quot;f&quot;: true, &quot;g&quot;: false, &quot;h&quot;: true, &quot;i&quot;: false, &quot;j&quot;: false, &quot;k&quot;: false }
10561</pre></div></div>
10562</li>
10563</ul>
10564<p>The function has three aliases: <tt>isdatetime</tt>, <tt>is_timestamp</tt>, and <tt>istimestamp</tt>.</p></div>
10565<div class="section">
10566<h3><a name="is_time"></a>is_time</h3>
10567<ul>
10568
10569<li>
10570
10571<p>Syntax:</p>
10572
10573<div>
10574<div>
10575<pre class="source">is_time(expr)
10576</pre></div></div>
10577</li>
10578<li>
10579
10580<p>Checks whether the given expression is evaluated to be a <tt>time</tt> value.</p>
10581</li>
10582<li>Arguments:
10583<ul>
10584
10585<li><tt>expr</tt> : an expression (any type is allowed).</li>
10586</ul>
10587</li>
10588<li>Return Value:
10589<ul>
10590
10591<li>a <tt>boolean</tt> on whether the argument is a <tt>time</tt> value or not,</li>
10592<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
10593<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
10594</ul>
10595</li>
10596<li>
10597
10598<p>Example:</p>
10599
10600<div>
10601<div>
10602<pre class="source"> {
10603 &quot;a&quot;: is_time(true),
10604 &quot;b&quot;: is_time(false),
10605 &quot;c&quot;: is_time(null),
10606 &quot;d&quot;: is_time(missing),
10607 &quot;e&quot;: is_time(time(&quot;08:00:00.000Z&quot;)),
10608 &quot;f&quot;: istime(date(&quot;2013-01-01&quot;)),
10609 &quot;g&quot;: istime(time(&quot;12:12:12.039Z&quot;)),
10610 &quot;h&quot;: istime(datetime(&quot;2013-01-01T12:12:12.039Z&quot;)),
10611 &quot;i&quot;: istime(duration(&quot;P100Y12MT12M&quot;)),
10612 &quot;j&quot;: istime(interval(date(&quot;2013-01-01&quot;), date(&quot;20130505&quot;))),
10613 &quot;k&quot;: istime(3)
10614};
10615</pre></div></div>
10616</li>
10617<li>
10618
10619<p>The expected result is:</p>
10620
10621<div>
10622<div>
10623<pre class="source">{ &quot;a&quot;: false, &quot;b&quot;: false, &quot;c&quot;: null, &quot;e&quot;: true, &quot;f&quot;: false, &quot;g&quot;: true, &quot;h&quot;: false, &quot;i&quot;: false, &quot;j&quot;: false, &quot;k&quot;: false }
10624</pre></div></div>
10625</li>
10626</ul>
10627<p>The function has an alias <tt>istime</tt>.</p></div>
10628<div class="section">
10629<h3><a name="is_duration"></a>is_duration</h3>
10630<ul>
10631
10632<li>
10633
10634<p>Syntax:</p>
10635
10636<div>
10637<div>
10638<pre class="source">is_duration(expr)
10639</pre></div></div>
10640</li>
10641<li>
10642
10643<p>Checks whether the given expression is evaluated to be a duration value.</p>
10644</li>
10645<li>Arguments:
10646<ul>
10647
10648<li><tt>expr</tt> : an expression (any type is allowed).</li>
10649</ul>
10650</li>
10651<li>Return Value:
10652<ul>
10653
10654<li>a <tt>boolean</tt> on whether the argument is a <tt>duration/year_month_duration/day_time_duration</tt> value or not,</li>
10655<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
10656<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
10657</ul>
10658</li>
10659<li>
10660
10661<p>Example:</p>
10662
10663<div>
10664<div>
10665<pre class="source"> {
10666 &quot;a&quot;: is_duration(true),
10667 &quot;b&quot;: is_duration(false),
10668 &quot;c&quot;: is_duration(null),
10669 &quot;d&quot;: is_duration(missing),
10670 &quot;e&quot;: is_duration(duration(&quot;-PT20.943S&quot;)),
10671 &quot;f&quot;: isduration(date(&quot;2013-01-01&quot;)),
10672 &quot;g&quot;: isduration(time(&quot;12:12:12.039Z&quot;)),
10673 &quot;h&quot;: isduration(datetime(&quot;2013-01-01T12:12:12.039Z&quot;)),
10674 &quot;i&quot;: isduration(duration(&quot;P100Y12MT12M&quot;)),
10675 &quot;j&quot;: isduration(interval(date(&quot;2013-01-01&quot;), date(&quot;20130505&quot;))),
10676 &quot;k&quot;: isduration(3)
10677};
10678</pre></div></div>
10679</li>
10680<li>
10681
10682<p>The expected result is:</p>
10683
10684<div>
10685<div>
10686<pre class="source">{ &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;: true, &quot;j&quot;: false, &quot;k&quot;: false }
10687</pre></div></div>
10688</li>
10689</ul>
10690<p>The function has an alias <tt>isduration</tt>.</p></div>
10691<div class="section">
10692<h3><a name="is_interval"></a>is_interval</h3>
10693<ul>
10694
10695<li>
10696
10697<p>Syntax:</p>
10698
10699<div>
10700<div>
10701<pre class="source">is_interval(expr)
10702</pre></div></div>
10703</li>
10704<li>
10705
10706<p>Checks whether the given expression is evaluated to be a <tt>interval</tt> value.</p>
10707</li>
10708<li>Arguments:
10709<ul>
10710
10711<li><tt>expr</tt> : an expression (any type is allowed).</li>
10712</ul>
10713</li>
10714<li>Return Value:
10715<ul>
10716
10717<li>a <tt>boolean</tt> on whether the argument is a <tt>interval</tt> value or not,</li>
10718<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
10719<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
10720</ul>
10721</li>
10722<li>
10723
10724<p>Example:</p>
10725
10726<div>
10727<div>
10728<pre class="source"> {
10729 &quot;a&quot;: is_interval(true),
10730 &quot;b&quot;: is_interval(false),
10731 &quot;c&quot;: is_interval(null),
10732 &quot;d&quot;: is_interval(missing),
10733 &quot;e&quot;: is_interval(interval(datetime(&quot;2013-01-01T00:01:01.000Z&quot;), datetime(&quot;2013-05-05T13:39:01.049Z&quot;))),
10734 &quot;f&quot;: isinterval(date(&quot;2013-01-01&quot;)),
10735 &quot;g&quot;: isinterval(time(&quot;12:12:12.039Z&quot;)),
10736 &quot;h&quot;: isinterval(datetime(&quot;2013-01-01T12:12:12.039Z&quot;)),
10737 &quot;i&quot;: isinterval(duration(&quot;P100Y12MT12M&quot;)),
10738 &quot;j&quot;: isinterval(interval(date(&quot;2013-01-01&quot;), date(&quot;20130505&quot;))),
10739 &quot;k&quot;: isinterval(3)
10740};
10741</pre></div></div>
10742</li>
10743<li>
10744
10745<p>The expected result is:</p>
10746
10747<div>
10748<div>
10749<pre class="source">{ &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, &quot;j&quot;: true, &quot;k&quot;: false }
10750</pre></div></div>
10751</li>
10752</ul>
10753<p>The function has an alias <tt>isinterval</tt>.</p></div>
10754<div class="section">
10755<h3><a name="is_temporal"></a>is_temporal</h3>
10756<ul>
10757
10758<li>
10759
10760<p>Syntax:</p>
10761
10762<div>
10763<div>
10764<pre class="source">is_temporal(expr)
10765</pre></div></div>
10766</li>
10767<li>
10768
10769<p>Checks whether the given expression is evaluated to be a temporal value.</p>
10770</li>
10771<li>Arguments:
10772<ul>
10773
10774<li><tt>expr</tt> : an expression (any type is allowed).</li>
10775</ul>
10776</li>
10777<li>Return Value:
10778<ul>
10779
10780<li>a <tt>boolean</tt> on whether the argument is a <tt>date/datetime/time/duration/year_month_duration/day_time_duration/interval</tt> value or not,</li>
10781<li>a <tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
10782<li>a <tt>null</tt> if the argument is a <tt>null</tt> value.</li>
10783</ul>
10784</li>
10785<li>
10786
10787<p>Example:</p>
10788
10789<div>
10790<div>
10791<pre class="source"> {
10792 &quot;a&quot;: is_temporal(true),
10793 &quot;b&quot;: is_temporal(false),
10794 &quot;c&quot;: is_temporal(null),
10795 &quot;d&quot;: is_temporal(missing),
10796 &quot;e&quot;: is_temporal(duration(&quot;-PT20.943S&quot;)),
10797 &quot;f&quot;: istemporal(date(&quot;2013-01-01&quot;)),
10798 &quot;g&quot;: istemporal(time(&quot;12:12:12.039Z&quot;)),
10799 &quot;h&quot;: istemporal(datetime(&quot;2013-01-01T12:12:12.039Z&quot;)),
10800 &quot;i&quot;: istemporal(duration(&quot;P100Y12MT12M&quot;)),
10801 &quot;j&quot;: istemporal(interval(date(&quot;2013-01-01&quot;), date(&quot;20130505&quot;))),
10802 &quot;k&quot;: istemporal(3)
10803};
10804</pre></div></div>
10805</li>
10806<li>
10807
10808<p>The expected result is:</p>
10809
10810<div>
10811<div>
10812<pre class="source">{ &quot;a&quot;: false, &quot;b&quot;: false, &quot;c&quot;: null, &quot;e&quot;: true, &quot;f&quot;: true, &quot;g&quot;: true, &quot;h&quot;: true, &quot;i&quot;: true, &quot;j&quot;: true, &quot;k&quot;: false }
10813</pre></div></div>
10814</li>
10815</ul>
10816<p>The function has an alias <tt>istemporal</tt>.</p></div>
10817<div class="section">
10818<h3><a name="get_type"></a>get_type</h3>
10819<ul>
10820
10821<li>
10822
10823<p>Syntax:</p>
10824
10825<div>
10826<div>
10827<pre class="source">get_type(expr)
10828</pre></div></div>
10829</li>
10830<li>
10831
10832<p>Returns a string describing the type of the given <tt>expr</tt>. This includes incomplete information types (i.e. <tt>missing</tt> and <tt>null</tt>).</p>
10833</li>
10834<li>Arguments:
10835<ul>
10836
10837<li><tt>expr</tt> : an expression (any type is allowed).</li>
10838</ul>
10839</li>
10840<li>
10841
10842<p>Example:</p>
10843
10844<div>
10845<div>
10846<pre class="source">{
10847 &quot;a&quot;: get_type(true),
10848 &quot;b&quot;: get_type(false),
10849 &quot;c&quot;: get_type(null),
10850 &quot;d&quot;: get_type(missing),
10851 &quot;e&quot;: get_type(&quot;d&quot;),
10852 &quot;f&quot;: gettype(4.0),
10853 &quot;g&quot;: gettype(5),
10854 &quot;h&quot;: gettype([&quot;1&quot;, 2]),
10855 &quot;i&quot;: gettype({&quot;a&quot;:1})
10856};
10857</pre></div></div>
10858</li>
10859<li>
10860
10861<p>The expected result is:</p>
10862
10863<div>
10864<div>
10865<pre class="source">{ &quot;a&quot;: &quot;boolean&quot;, &quot;b&quot;: &quot;boolean&quot;, &quot;c&quot;: &quot;null&quot;, &quot;d&quot;: &quot;missing&quot;, &quot;e&quot;: &quot;string&quot;, &quot;f&quot;: &quot;double&quot;, &quot;g&quot;: &quot;bigint&quot;, &quot;h&quot;: &quot;array&quot;, &quot;i&quot;: &quot;object&quot; }
10866</pre></div></div>
10867</li>
10868</ul>
10869<p>The function has an alias <tt>gettype</tt>.</p><!--
10870 ! Licensed to the Apache Software Foundation (ASF) under one
10871 ! or more contributor license agreements. See the NOTICE file
10872 ! distributed with this work for additional information
10873 ! regarding copyright ownership. The ASF licenses this file
10874 ! to you under the Apache License, Version 2.0 (the
10875 ! "License"); you may not use this file except in compliance
10876 ! with the License. You may obtain a copy of the License at
10877 !
10878 ! http://www.apache.org/licenses/LICENSE-2.0
10879 !
10880 ! Unless required by applicable law or agreed to in writing,
10881 ! software distributed under the License is distributed on an
10882 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
10883 ! KIND, either express or implied. See the License for the
10884 ! specific language governing permissions and limitations
10885 ! under the License.
10886 !-->
10887</div>
10888<div class="section">
10889<h3><a name="to_array"></a>to_array</h3>
10890<ul>
10891
10892<li>
10893
10894<p>Syntax:</p>
10895
10896<div>
10897<div>
10898<pre class="source">to_array(expr)
10899</pre></div></div>
10900</li>
10901<li>
10902
10903<p>Converts input value to an <tt>array</tt> value</p>
10904</li>
10905<li>Arguments:
10906<ul>
10907
10908<li><tt>expr</tt> : an expression</li>
10909</ul>
10910</li>
10911<li>Return Value:
10912<ul>
10913
10914<li>if the argument is <tt>missing</tt> then <tt>missing</tt> is returned</li>
10915<li>if the argument is <tt>null</tt> then <tt>null</tt> is returned</li>
10916<li>if the argument is of <tt>array</tt> type then it is returned as is</li>
10917<li>if the argument is of <tt>multiset</tt> type then it is returned as an <tt>array</tt> with elements in an undefined order</li>
10918<li>otherwise an <tt>array</tt> containing the input expression as its single item is returned</li>
10919</ul>
10920</li>
10921<li>
10922
10923<p>Example:</p>
10924
10925<div>
10926<div>
10927<pre class="source">{
10928 &quot;v1&quot;: to_array(&quot;asterix&quot;),
10929 &quot;v2&quot;: to_array([&quot;asterix&quot;]),
10930};
10931</pre></div></div>
10932</li>
10933<li>
10934
10935<p>The expected result is:</p>
10936
10937<div>
10938<div>
10939<pre class="source">{ &quot;v1&quot;: [&quot;asterix&quot;], &quot;v2&quot;: [&quot;asterix&quot;] }
10940</pre></div></div>
10941</li>
10942</ul>
10943<p>The function has an alias <tt>toarray</tt>.</p></div>
10944<div class="section">
10945<h3><a name="to_atomic_.28to_atom.29"></a>to_atomic (to_atom)</h3>
10946<ul>
10947
10948<li>
10949
10950<p>Syntax:</p>
10951
10952<div>
10953<div>
10954<pre class="source">to_atomic(expr)
10955</pre></div></div>
10956</li>
10957<li>
10958
10959<p>Converts input value to a <a href="../datamodel.html#PrimitiveTypes">primitive</a> value</p>
10960</li>
10961<li>Arguments:
10962<ul>
10963
10964<li><tt>expr</tt> : an expression</li>
10965</ul>
10966</li>
10967<li>Return Value:
10968<ul>
10969
10970<li>if the argument is <tt>missing</tt> then <tt>missing</tt> is returned</li>
10971<li>if the argument is <tt>null</tt> then <tt>null</tt> is returned</li>
10972<li>if the argument is of primitive type then it is returned as is</li>
10973<li>if the argument is of <tt>array</tt> or <tt>multiset</tt> type and has only one element then the result of invoking to_atomic() on that element is returned</li>
10974<li>if the argument is of <tt>object</tt> type and has only one field then the result of invoking to_atomic() on the value of that field is returned</li>
10975<li>otherwise <tt>null</tt> is returned</li>
10976</ul>
10977</li>
10978<li>
10979
10980<p>Example:</p>
10981
10982<div>
10983<div>
10984<pre class="source">{
10985 &quot;v1&quot;: to_atomic(&quot;asterix&quot;),
10986 &quot;v2&quot;: to_atomic([&quot;asterix&quot;]),
10987 &quot;v3&quot;: to_atomic([0, 1]),
10988 &quot;v4&quot;: to_atomic({&quot;value&quot;: &quot;asterix&quot;}),
10989 &quot;v5&quot;: to_number({&quot;x&quot;: 1, &quot;y&quot;: 2})
10990};
10991</pre></div></div>
10992</li>
10993<li>
10994
10995<p>The expected result is:</p>
10996
10997<div>
10998<div>
10999<pre class="source">{ &quot;v1&quot;: &quot;asterix&quot;, &quot;v2&quot;: &quot;asterix&quot;, &quot;v3&quot;: null, &quot;v4&quot;: &quot;asterix&quot;, &quot;v5&quot;: null }
11000</pre></div></div>
11001</li>
11002</ul>
11003<p>The function has three aliases: <tt>toatomic</tt>, <tt>to_atom</tt>, and <tt>toatom</tt>.</p></div>
11004<div class="section">
11005<h3><a name="to_boolean_.28to_bool.29"></a>to_boolean (to_bool)</h3>
11006<ul>
11007
11008<li>
11009
11010<p>Syntax:</p>
11011
11012<div>
11013<div>
11014<pre class="source">to_boolean(expr)
11015</pre></div></div>
11016</li>
11017<li>
11018
11019<p>Converts input value to a <tt>boolean</tt> value</p>
11020</li>
11021<li>Arguments:
11022<ul>
11023
11024<li><tt>expr</tt> : an expression</li>
11025</ul>
11026</li>
11027<li>Return Value:
11028<ul>
11029
11030<li>if the argument is <tt>missing</tt> then <tt>missing</tt> is returned</li>
11031<li>if the argument is <tt>null</tt> then <tt>null</tt> is returned</li>
11032<li>if the argument is of <tt>boolean</tt> type then it is returned as is</li>
11033<li>if the argument is of numeric type then <tt>false</tt> is returned if it is <tt>0</tt> or <tt>NaN</tt>, otherwise <tt>true</tt></li>
11034<li>if the argument is of <tt>string</tt> type then <tt>false</tt> is returned if it&#x2019;s empty, otherwise <tt>true</tt></li>
11035<li>if the argument is of <tt>array</tt> or <tt>multiset</tt> type then <tt>false</tt> is returned if it&#x2019;s size is <tt>0</tt>, otherwise <tt>true</tt></li>
11036<li>if the argument is of <tt>object</tt> type then <tt>false</tt> is returned if it has no fields, otherwise <tt>true</tt></li>
11037<li>type error is raised for all other input types</li>
11038</ul>
11039</li>
11040<li>
11041
11042<p>Example:</p>
11043
11044<div>
11045<div>
11046<pre class="source">{
11047 &quot;v1&quot;: to_boolean(0),
11048 &quot;v2&quot;: to_boolean(1),
11049 &quot;v3&quot;: to_boolean(&quot;&quot;),
11050 &quot;v4&quot;: to_boolean(&quot;asterix&quot;)
11051};
11052</pre></div></div>
11053</li>
11054<li>
11055
11056<p>The expected result is:</p>
11057
11058<div>
11059<div>
11060<pre class="source">{ &quot;v1&quot;: false, &quot;v2&quot;: true, &quot;v3&quot;: false, &quot;v4&quot;: true }
11061</pre></div></div>
11062</li>
11063</ul>
11064<p>The function has three aliases: <tt>toboolean</tt>, <tt>to_bool</tt>, and <tt>tobool</tt>.</p></div>
11065<div class="section">
11066<h3><a name="to_bigint"></a>to_bigint</h3>
11067<ul>
11068
11069<li>
11070
11071<p>Syntax:</p>
11072
11073<div>
11074<div>
11075<pre class="source">to_bigint(expr)
11076</pre></div></div>
11077</li>
11078<li>
11079
11080<p>Converts input value to an integer value</p>
11081</li>
11082<li>Arguments:
11083<ul>
11084
11085<li><tt>expr</tt> : an expression</li>
11086</ul>
11087</li>
11088<li>Return Value:
11089<ul>
11090
11091<li>if the argument is <tt>missing</tt> then <tt>missing</tt> is returned</li>
11092<li>if the argument is <tt>null</tt> then <tt>null</tt> is returned</li>
11093<li>if the argument is of <tt>boolean</tt> type then <tt>1</tt> is returned if it is <tt>true</tt>, <tt>0</tt> if it is <tt>false</tt></li>
11094<li>if the argument is of numeric integer type then it is returned as the same value of <tt>bigint</tt> type</li>
11095<li>if the argument is of numeric <tt>float</tt>/<tt>double</tt> type then it is converted to <tt>bigint</tt> type</li>
11096<li>if the argument is of <tt>string</tt> type and can be parsed as integer then that integer value is returned, otherwise <tt>null</tt> is returned</li>
11097<li>if the argument is of <tt>array</tt>/<tt>multiset</tt>/<tt>object</tt> type then <tt>null</tt> is returned</li>
11098<li>type error is raised for all other input types</li>
11099</ul>
11100</li>
11101<li>
11102
11103<p>Example:</p>
11104
11105<div>
11106<div>
11107<pre class="source">{
11108 &quot;v1&quot;: to_bigint(false),
11109 &quot;v2&quot;: to_bigint(true),
11110 &quot;v3&quot;: to_bigint(10),
11111 &quot;v4&quot;: to_bigint(float(&quot;1e100&quot;)),
11112 &quot;v5&quot;: to_bigint(double(&quot;1e1000&quot;)),
11113 &quot;v6&quot;: to_bigint(&quot;20&quot;)
11114};
11115</pre></div></div>
11116</li>
11117<li>
11118
11119<p>The expected result is:</p>
11120
11121<div>
11122<div>
11123<pre class="source">{ &quot;v1&quot;: 0, &quot;v2&quot;: 1, &quot;v3&quot;: 10, &quot;v4&quot;: 9223372036854775807, &quot;v5&quot;: 9223372036854775807, &quot;v6&quot;: 20 }
11124</pre></div></div>
11125</li>
11126</ul>
11127<p>The function has an alias <tt>tobigint</tt>.</p></div>
11128<div class="section">
11129<h3><a name="to_double"></a>to_double</h3>
11130<ul>
11131
11132<li>
11133
11134<p>Syntax:</p>
11135
11136<div>
11137<div>
11138<pre class="source">to_double(expr)
11139</pre></div></div>
11140</li>
11141<li>
11142
11143<p>Converts input value to a <tt>double</tt> value</p>
11144</li>
11145<li>Arguments:
11146<ul>
11147
11148<li><tt>expr</tt> : an expression</li>
11149</ul>
11150</li>
11151<li>Return Value:
11152<ul>
11153
11154<li>if the argument is <tt>missing</tt> then <tt>missing</tt> is returned</li>
11155<li>if the argument is <tt>null</tt> then <tt>null</tt> is returned</li>
11156<li>if the argument is of <tt>boolean</tt> type then <tt>1.0</tt> is returned if it is <tt>true</tt>, <tt>0.0</tt> if it is <tt>false</tt></li>
11157<li>if the argument is of numeric type then it is returned as the value of <tt>double</tt> type</li>
11158<li>if the argument is of <tt>string</tt> type and can be parsed as <tt>double</tt> then that <tt>double</tt> value is returned, otherwise <tt>null</tt> is returned</li>
11159<li>if the argument is of <tt>array</tt>/<tt>multiset</tt>/<tt>object</tt> type then <tt>null</tt> is returned</li>
11160<li>type error is raised for all other input types</li>
11161</ul>
11162</li>
11163<li>
11164
11165<p>Example:</p>
11166
11167<div>
11168<div>
11169<pre class="source">{
11170 &quot;v1&quot;: to_double(false),
11171 &quot;v2&quot;: to_double(true),
11172 &quot;v3&quot;: to_double(10),
11173 &quot;v4&quot;: to_double(11.5),
11174 &quot;v5&quot;: to_double(&quot;12.5&quot;)
11175};
11176</pre></div></div>
11177</li>
11178<li>
11179
11180<p>The expected result is:</p>
11181
11182<div>
11183<div>
11184<pre class="source">{ &quot;v1&quot;: 0.0, &quot;v2&quot;: 1.0, &quot;v3&quot;: 10.0, &quot;v4&quot;: 11.5, &quot;v5&quot;: 12.5 }
11185</pre></div></div>
11186</li>
11187</ul>
11188<p>The function has an alias <tt>todouble</tt>.</p></div>
11189<div class="section">
11190<h3><a name="to_number_.28to_num.29"></a>to_number (to_num)</h3>
11191<ul>
11192
11193<li>
11194
11195<p>Syntax:</p>
11196
11197<div>
11198<div>
11199<pre class="source">to_number(expr)
11200</pre></div></div>
11201</li>
11202<li>
11203
11204<p>Converts input value to a numeric value</p>
11205</li>
11206<li>Arguments:
11207<ul>
11208
11209<li><tt>expr</tt> : an expression</li>
11210</ul>
11211</li>
11212<li>Return Value:
11213<ul>
11214
11215<li>if the argument is <tt>missing</tt> then <tt>missing</tt> is returned</li>
11216<li>if the argument is <tt>null</tt> then <tt>null</tt> is returned</li>
11217<li>if the argument is of numeric type then it is returned as is</li>
11218<li>if the argument is of <tt>boolean</tt> type then <tt>1</tt> is returned if it is <tt>true</tt>, <tt>0</tt> if it is <tt>false</tt></li>
11219<li>if the argument is of <tt>string</tt> type and can be parsed as <tt>bigint</tt> then that <tt>bigint</tt> value is returned, otherwise if it can be parsed as <tt>double</tt> then that <tt>double</tt> value is returned, otherwise <tt>null</tt> is returned</li>
11220<li>if the argument is of <tt>array</tt>/<tt>multiset</tt>/<tt>object</tt> type then <tt>null</tt> is returned</li>
11221<li>type error is raised for all other input types</li>
11222</ul>
11223</li>
11224<li>
11225
11226<p>Example:</p>
11227
11228<div>
11229<div>
11230<pre class="source">{
11231 &quot;v1&quot;: to_number(false),
11232 &quot;v2&quot;: to_number(true),
11233 &quot;v3&quot;: to_number(10),
11234 &quot;v4&quot;: to_number(11.5),
11235 &quot;v5&quot;: to_number(&quot;12.5&quot;)
11236};
11237</pre></div></div>
11238</li>
11239<li>
11240
11241<p>The expected result is:</p>
11242
11243<div>
11244<div>
11245<pre class="source">{ &quot;v1&quot;: 0, &quot;v2&quot;: 1, &quot;v3&quot;: 10, &quot;v4&quot;: 11.5, &quot;v5&quot;: 12.5 }
11246</pre></div></div>
11247</li>
11248</ul>
11249<p>The function has three aliases: <tt>tonumber</tt>, <tt>to_num</tt>, and <tt>tonum</tt>.</p></div>
11250<div class="section">
11251<h3><a name="to_object_.28to_obj.29"></a>to_object (to_obj)</h3>
11252<ul>
11253
11254<li>
11255
11256<p>Syntax:</p>
11257
11258<div>
11259<div>
11260<pre class="source">to_object(expr)
11261</pre></div></div>
11262</li>
11263<li>
11264
11265<p>Converts input value to an <tt>object</tt> value</p>
11266</li>
11267<li>Arguments:
11268<ul>
11269
11270<li><tt>expr</tt> : an expression</li>
11271</ul>
11272</li>
11273<li>Return Value:
11274<ul>
11275
11276<li>if the argument is <tt>missing</tt> then <tt>missing</tt> is returned</li>
11277<li>if the argument is <tt>null</tt> then <tt>null</tt> is returned</li>
11278<li>if the argument is of <tt>object</tt> type then it is returned as is</li>
11279<li>otherwise an empty <tt>object</tt> is returned</li>
11280</ul>
11281</li>
11282<li>
11283
11284<p>Example:</p>
11285
11286<div>
11287<div>
11288<pre class="source">{
11289 &quot;v1&quot;: to_object({&quot;value&quot;: &quot;asterix&quot;}),
11290 &quot;v2&quot;: to_object(&quot;asterix&quot;)
11291};
11292</pre></div></div>
11293</li>
11294<li>
11295
11296<p>The expected result is:</p>
11297
11298<div>
11299<div>
11300<pre class="source">{ &quot;v1&quot;: {&quot;value&quot;: &quot;asterix&quot;}, &quot;v2&quot;: {} }
11301</pre></div></div>
11302</li>
11303</ul>
11304<p>The function has three aliases: <tt>toobject</tt>, <tt>to_obj</tt>, and <tt>toobj</tt>.</p></div>
11305<div class="section">
11306<h3><a name="to_string_.28to_str.29"></a>to_string (to_str)</h3>
11307<ul>
11308
11309<li>
11310
11311<p>Syntax:</p>
11312
11313<div>
11314<div>
11315<pre class="source">to_string(expr)
11316</pre></div></div>
11317</li>
11318<li>
11319
11320<p>Converts input value to a string value</p>
11321</li>
11322<li>Arguments:
11323<ul>
11324
11325<li><tt>expr</tt> : an expression</li>
11326</ul>
11327</li>
11328<li>Return Value:
11329<ul>
11330
11331<li>if the argument is <tt>missing</tt> then <tt>missing</tt> is returned</li>
11332<li>if the argument is <tt>null</tt> then <tt>null</tt> is returned</li>
11333<li>if the argument is of <tt>boolean</tt> type then <tt>&quot;true&quot;</tt> is returned if it is <tt>true</tt>, <tt>&quot;false&quot;</tt> if it is <tt>false</tt></li>
11334<li>if the argument is of numeric type then its string representation is returned</li>
11335<li>if the argument is of <tt>string</tt> type then it is returned as is</li>
11336<li>if the argument is of <tt>array</tt>/<tt>multiset</tt>/<tt>object</tt> type then <tt>null</tt> is returned</li>
11337<li>type error is raised for all other input types</li>
11338</ul>
11339</li>
11340<li>
11341
11342<p>Example:</p>
11343
11344<div>
11345<div>
11346<pre class="source">{
11347 &quot;v1&quot;: to_string(false),
11348 &quot;v2&quot;: to_string(true),
11349 &quot;v3&quot;: to_string(10),
11350 &quot;v4&quot;: to_string(11.5),
11351 &quot;v5&quot;: to_string(&quot;asterix&quot;)
11352};
11353</pre></div></div>
11354</li>
11355<li>
11356
11357<p>The expected result is:</p>
11358
11359<div>
11360<div>
11361<pre class="source">{ &quot;v1&quot;: &quot;false&quot;, &quot;v2&quot;: &quot;true&quot;, &quot;v3&quot;: &quot;10&quot;, &quot;v4&quot;: &quot;11.5&quot;, &quot;v5&quot;: &quot;asterix&quot; }
11362</pre></div></div>
11363</li>
11364</ul>
11365<p>The function has three aliases: <tt>tostring</tt>, <tt>to_str</tt>, and <tt>tostr</tt>.</p><!--
11366 ! Licensed to the Apache Software Foundation (ASF) under one
11367 ! or more contributor license agreements. See the NOTICE file
11368 ! distributed with this work for additional information
11369 ! regarding copyright ownership. The ASF licenses this file
11370 ! to you under the Apache License, Version 2.0 (the
11371 ! "License"); you may not use this file except in compliance
11372 ! with the License. You may obtain a copy of the License at
11373 !
11374 ! http://www.apache.org/licenses/LICENSE-2.0
11375 !
11376 ! Unless required by applicable law or agreed to in writing,
11377 ! software distributed under the License is distributed on an
11378 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
11379 ! KIND, either express or implied. See the License for the
11380 ! specific language governing permissions and limitations
11381 ! under the License.
11382 !-->
11383</div></div>
11384<div class="section">
11385<h2><a name="Conditional_Functions"></a><a name="ConditionalFunctions" id="ConditionalFunctions">Conditional Functions</a></h2>
11386<div class="section">
11387<h3><a name="if_null_.28ifnull.29"></a>if_null (ifnull)</h3>
11388<ul>
11389
11390<li>
11391
11392<p>Syntax:</p>
11393
11394<div>
11395<div>
11396<pre class="source">if_null(expression1, expression2, ... expressionN)
11397</pre></div></div>
11398</li>
11399<li>
11400
11401<p>Finds first argument which value is not <tt>null</tt> and returns that value</p>
11402</li>
11403<li>Arguments:
11404<ul>
11405
11406<li><tt>expressionI</tt> : an expression (any type is allowed).</li>
11407</ul>
11408</li>
11409<li>Return Value:
11410<ul>
11411
11412<li>a <tt>null</tt> if all arguments evaluate to <tt>null</tt> or no arguments specified</li>
11413<li>a value of the first non-<tt>null</tt> argument otherwise</li>
11414</ul>
11415</li>
11416<li>
11417
11418<p>Example:</p>
11419
11420<div>
11421<div>
11422<pre class="source">{
11423 &quot;a&quot;: if_null(),
11424 &quot;b&quot;: if_null(null),
11425 &quot;c&quot;: if_null(null, &quot;asterixdb&quot;),
11426 &quot;d&quot;: is_missing(if_null(missing))
11427};
11428</pre></div></div>
11429</li>
11430<li>
11431
11432<p>The expected result is:</p>
11433
11434<div>
11435<div>
11436<pre class="source">{ &quot;a&quot;: null, &quot;b&quot;: null, &quot;c&quot;: &quot;asterixdb&quot;, &quot;d&quot;: true }
11437</pre></div></div>
11438</li>
11439</ul>
11440<p>The function has an alias <tt>ifnull</tt>.</p></div>
11441<div class="section">
11442<h3><a name="if_missing_.28ifmissing.29"></a>if_missing (ifmissing)</h3>
11443<ul>
11444
11445<li>
11446
11447<p>Syntax:</p>
11448
11449<div>
11450<div>
11451<pre class="source">if_missing(expression1, expression2, ... expressionN)
11452</pre></div></div>
11453</li>
11454<li>
11455
11456<p>Finds first argument which value is not <tt>missing</tt> and returns that value</p>
11457</li>
11458<li>Arguments:
11459<ul>
11460
11461<li><tt>expressionI</tt> : an expression (any type is allowed).</li>
11462</ul>
11463</li>
11464<li>Return Value:
11465<ul>
11466
11467<li>a <tt>null</tt> if all arguments evaluate to <tt>missing</tt> or no arguments specified</li>
11468<li>a value of the first non-<tt>missing</tt> argument otherwise</li>
11469</ul>
11470</li>
11471<li>
11472
11473<p>Example:</p>
11474
11475<div>
11476<div>
11477<pre class="source">{
11478 &quot;a&quot;: if_missing(),
11479 &quot;b&quot;: if_missing(missing),
11480 &quot;c&quot;: if_missing(missing, &quot;asterixdb&quot;),
11481 &quot;d&quot;: if_missing(null, &quot;asterixdb&quot;)
11482};
11483</pre></div></div>
11484</li>
11485<li>
11486
11487<p>The expected result is:</p>
11488
11489<div>
11490<div>
11491<pre class="source">{ &quot;a&quot;: null, &quot;b&quot;: null, &quot;c&quot;: &quot;asterixdb&quot;, &quot;d&quot;: null }
11492</pre></div></div>
11493</li>
11494</ul>
11495<p>The function has an alias <tt>ifmissing</tt>.</p></div>
11496<div class="section">
11497<h3><a name="if_missing_or_null_.28ifmissingornull.2C_coalesce.29"></a>if_missing_or_null (ifmissingornull, coalesce)</h3>
11498<ul>
11499
11500<li>
11501
11502<p>Syntax:</p>
11503
11504<div>
11505<div>
11506<pre class="source">if_missing_or_null(expression1, expression2, ... expressionN)
11507</pre></div></div>
11508</li>
11509<li>
11510
11511<p>Finds first argument which value is not <tt>null</tt> or <tt>missing</tt> and returns that value</p>
11512</li>
11513<li>Arguments:
11514<ul>
11515
11516<li><tt>expressionI</tt> : an expression (any type is allowed).</li>
11517</ul>
11518</li>
11519<li>Return Value:
11520<ul>
11521
11522<li>a <tt>null</tt> if all arguments evaluate to either <tt>null</tt> or <tt>missing</tt>, or no arguments specified</li>
11523<li>a value of the first non-<tt>null</tt>, non-<tt>missing</tt> argument otherwise</li>
11524</ul>
11525</li>
11526<li>
11527
11528<p>Example:</p>
11529
11530<div>
11531<div>
11532<pre class="source">{
11533 &quot;a&quot;: if_missing_or_null(),
11534 &quot;b&quot;: if_missing_or_null(null, missing),
11535 &quot;c&quot;: if_missing_or_null(null, missing, &quot;asterixdb&quot;)
11536};
11537</pre></div></div>
11538</li>
11539<li>
11540
11541<p>The expected result is:</p>
11542
11543<div>
11544<div>
11545<pre class="source">{ &quot;a&quot;: null, &quot;b&quot;: null, &quot;c&quot;: &quot;asterixdb&quot; }
11546</pre></div></div>
11547</li>
11548</ul>
11549<p>The function has two aliases: <tt>ifmissingornull</tt> and <tt>coalesce</tt>.</p></div>
11550<div class="section">
11551<h3><a name="if_inf_.28ifinf.29"></a>if_inf (ifinf)</h3>
11552<ul>
11553
11554<li>
11555
11556<p>Syntax:</p>
11557
11558<div>
11559<div>
11560<pre class="source">if_inf(expression1, expression2, ... expressionN)
11561</pre></div></div>
11562</li>
11563<li>
11564
11565<p>Finds first argument which is a non-infinite (<tt>INF</tt> or<tt>-INF</tt>) number</p>
11566</li>
11567<li>Arguments:
11568<ul>
11569
11570<li><tt>expressionI</tt> : an expression (any type is allowed).</li>
11571</ul>
11572</li>
11573<li>Return Value:
11574<ul>
11575
11576<li>a <tt>missing</tt> if <tt>missing</tt> argument was encountered before the first non-infinite number argument</li>
11577<li>a <tt>null</tt> if <tt>null</tt> argument or any other non-number argument was encountered before the first non-infinite number argument</li>
11578<li>the first non-infinite number argument otherwise</li>
11579</ul>
11580</li>
11581<li>
11582
11583<p>Example:</p>
11584
11585<div>
11586<div>
11587<pre class="source">{
11588 &quot;a&quot;: is_null(if_inf(null)),
11589 &quot;b&quot;: is_missing(if_inf(missing)),
11590 &quot;c&quot;: is_null(if_inf(double(&quot;INF&quot;))),
11591 &quot;d&quot;: if_inf(1, null, missing) ],
11592 &quot;e&quot;: is_null(if_inf(null, missing, 1)) ],
11593 &quot;f&quot;: is_missing(if_inf(missing, null, 1)) ],
11594 &quot;g&quot;: if_inf(float(&quot;INF&quot;), 1) ],
11595 &quot;h&quot;: to_string(if_inf(float(&quot;INF&quot;), double(&quot;NaN&quot;), 1)) ]
11596};
11597</pre></div></div>
11598</li>
11599<li>
11600
11601<p>The expected result is:</p>
11602
11603<div>
11604<div>
11605<pre class="source">{ &quot;a&quot;: true, &quot;b&quot;: true, &quot;c&quot;: true, &quot;d&quot;: 1, &quot;e&quot;: true, &quot;f&quot;: true, &quot;g&quot;: 1, &quot;h&quot;: &quot;NaN&quot; }
11606</pre></div></div>
11607</li>
11608</ul>
11609<p>The function has an alias <tt>ifinf</tt>.</p></div>
11610<div class="section">
11611<h3><a name="if_nan_.28ifnan.29"></a>if_nan (ifnan)</h3>
11612<ul>
11613
11614<li>
11615
11616<p>Syntax:</p>
11617
11618<div>
11619<div>
11620<pre class="source">if_nan(expression1, expression2, ... expressionN)
11621</pre></div></div>
11622</li>
11623<li>
11624
11625<p>Finds first argument which is a non-<tt>NaN</tt> number</p>
11626</li>
11627<li>Arguments:
11628<ul>
11629
11630<li><tt>expressionI</tt> : an expression (any type is allowed).</li>
11631</ul>
11632</li>
11633<li>Return Value:
11634<ul>
11635
11636<li>a <tt>missing</tt> if <tt>missing</tt> argument was encountered before the first non-<tt>NaN</tt> number argument</li>
11637<li>a <tt>null</tt> if <tt>null</tt> argument or any other non-number argument was encountered before the first non-<tt>NaN</tt> number argument</li>
11638<li>the first non-<tt>NaN</tt> number argument otherwise</li>
11639</ul>
11640</li>
11641<li>
11642
11643<p>Example:</p>
11644
11645<div>
11646<div>
11647<pre class="source">{
11648 &quot;a&quot;: is_null(if_nan(null)),
11649 &quot;b&quot;: is_missing(if_nan(missing)),
11650 &quot;c&quot;: is_null(if_nan(double(&quot;NaN&quot;))),
11651 &quot;d&quot;: if_nan(1, null, missing) ],
11652 &quot;e&quot;: is_null(if_nan(null, missing, 1)) ],
11653 &quot;f&quot;: is_missing(if_nan(missing, null, 1)) ],
11654 &quot;g&quot;: if_nan(float(&quot;NaN&quot;), 1) ],
11655 &quot;h&quot;: to_string(if_nan(float(&quot;NaN&quot;), double(&quot;INF&quot;), 1)) ]
11656};
11657</pre></div></div>
11658</li>
11659<li>
11660
11661<p>The expected result is:</p>
11662
11663<div>
11664<div>
11665<pre class="source">{ &quot;a&quot;: true, &quot;b&quot;: true, &quot;c&quot;: true, &quot;d&quot;: 1, &quot;e&quot;: true, &quot;f&quot;: true, &quot;g&quot;: 1, &quot;h&quot;: &quot;INF&quot; }
11666</pre></div></div>
11667</li>
11668</ul>
11669<p>The function has an alias <tt>ifnan</tt>.</p></div>
11670<div class="section">
11671<h3><a name="if_nan_or_inf_.28ifnanorinf.29"></a>if_nan_or_inf (ifnanorinf)</h3>
11672<ul>
11673
11674<li>
11675
11676<p>Syntax:</p>
11677
11678<div>
11679<div>
11680<pre class="source">if_nan_or_inf(expression1, expression2, ... expressionN)
11681</pre></div></div>
11682</li>
11683<li>
11684
11685<p>Finds first argument which is a non-infinite (<tt>INF</tt> or<tt>-INF</tt>) and non-<tt>NaN</tt> number</p>
11686</li>
11687<li>Arguments:
11688<ul>
11689
11690<li><tt>expressionI</tt> : an expression (any type is allowed).</li>
11691</ul>
11692</li>
11693<li>Return Value:
11694<ul>
11695
11696<li>a <tt>missing</tt> if <tt>missing</tt> argument was encountered before the first non-infinite and non-<tt>NaN</tt> number argument</li>
11697<li>a <tt>null</tt> if <tt>null</tt> argument or any other non-number argument was encountered before the first non-infinite and non-<tt>NaN</tt> number argument</li>
11698<li>the first non-infinite and non-<tt>NaN</tt> number argument otherwise</li>
11699</ul>
11700</li>
11701<li>
11702
11703<p>Example:</p>
11704
11705<div>
11706<div>
11707<pre class="source">{
11708 &quot;a&quot;: is_null(if_nan_or_inf(null)),
11709 &quot;b&quot;: is_missing(if_nan_or_inf(missing)),
11710 &quot;c&quot;: is_null(if_nan_or_inf(double(&quot;NaN&quot;), double(&quot;INF&quot;))),
11711 &quot;d&quot;: if_nan_or_inf(1, null, missing) ],
11712 &quot;e&quot;: is_null(if_nan_or_inf(null, missing, 1)) ],
11713 &quot;f&quot;: is_missing(if_nan_or_inf(missing, null, 1)) ],
11714 &quot;g&quot;: if_nan_or_inf(float(&quot;NaN&quot;), float(&quot;INF&quot;), 1) ],
11715};
11716</pre></div></div>
11717</li>
11718<li>
11719
11720<p>The expected result is:</p>
11721
11722<div>
11723<div>
11724<pre class="source">{ &quot;a&quot;: true, &quot;b&quot;: true, &quot;c&quot;: true, &quot;d&quot;: 1, &quot;e&quot;: true, &quot;f&quot;: true, &quot;g&quot;: 1 }
11725</pre></div></div>
11726</li>
11727</ul>
11728<p>The function has an alias <tt>ifnanorinf</tt>.</p></div>
11729<div class="section">
11730<h3><a name="null_if_.28nullif.29"></a>null_if (nullif)</h3>
11731<ul>
11732
11733<li>
11734
11735<p>Syntax:</p>
11736
11737<div>
11738<div>
11739<pre class="source">null_if(expression1, expression2)
11740</pre></div></div>
11741</li>
11742<li>
11743
11744<p>Compares two arguments and returns <tt>null</tt> if they are equal, otherwise returns the first argument.</p>
11745</li>
11746<li>Arguments:
11747<ul>
11748
11749<li><tt>expressionI</tt> : an expression (any type is allowed).</li>
11750</ul>
11751</li>
11752<li>Return Value:
11753<ul>
11754
11755<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
11756<li><tt>null</tt> if
11757<ul>
11758
11759<li>any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value, or</li>
11760<li><tt>argument1</tt> = <tt>argument2</tt></li>
11761</ul>
11762</li>
11763<li>a value of the first argument otherwise</li>
11764</ul>
11765</li>
11766<li>
11767
11768<p>Example:</p>
11769
11770<div>
11771<div>
11772<pre class="source">{
11773 &quot;a&quot;: null_if(&quot;asterixdb&quot;, &quot;asterixdb&quot;),
11774 &quot;b&quot;: null_if(1, 2)
11775};
11776</pre></div></div>
11777</li>
11778<li>
11779
11780<p>The expected result is:</p>
11781
11782<div>
11783<div>
11784<pre class="source">{ &quot;a&quot;: null, &quot;b&quot;: 1 }
11785</pre></div></div>
11786</li>
11787</ul>
11788<p>The function has an alias <tt>nullif</tt>.</p></div>
11789<div class="section">
11790<h3><a name="missing_if_.28missingif.29"></a>missing_if (missingif)</h3>
11791<ul>
11792
11793<li>
11794
11795<p>Syntax:</p>
11796
11797<div>
11798<div>
11799<pre class="source">missing_if(expression1, expression2)
11800</pre></div></div>
11801</li>
11802<li>
11803
11804<p>Compares two arguments and returns <tt>missing</tt> if they are equal, otherwise returns the first argument.</p>
11805</li>
11806<li>Arguments:
11807<ul>
11808
11809<li><tt>expressionI</tt> : an expression (any type is allowed).</li>
11810</ul>
11811</li>
11812<li>Return Value:
11813<ul>
11814
11815<li><tt>missing</tt> if
11816<ul>
11817
11818<li>any argument is a <tt>missing</tt> value, or</li>
11819<li>no argument is a <tt>null</tt> value and <tt>argument1</tt> = <tt>argument2</tt></li>
11820</ul>
11821</li>
11822<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value</li>
11823<li>a value of the first argument otherwise</li>
11824</ul>
11825</li>
11826<li>
11827
11828<p>Example:</p>
11829
11830<div>
11831<div>
11832<pre class="source">{
11833 &quot;a&quot;: missing_if(&quot;asterixdb&quot;, &quot;asterixdb&quot;)
11834 &quot;b&quot;: missing_if(1, 2),
11835};
11836</pre></div></div>
11837</li>
11838<li>
11839
11840<p>The expected result is:</p>
11841
11842<div>
11843<div>
11844<pre class="source">{ &quot;b&quot;: 1 }
11845</pre></div></div>
11846</li>
11847</ul>
11848<p>The function has an alias <tt>missingif</tt>.</p></div>
11849<div class="section">
11850<h3><a name="nan_if_.28nanif.29"></a>nan_if (nanif)</h3>
11851<ul>
11852
11853<li>
11854
11855<p>Syntax:</p>
11856
11857<div>
11858<div>
11859<pre class="source">nan_if(expression1, expression2)
11860</pre></div></div>
11861</li>
11862<li>
11863
11864<p>Compares two arguments and returns <tt>NaN</tt> value if they are equal, otherwise returns the first argument.</p>
11865</li>
11866<li>Arguments:
11867<ul>
11868
11869<li><tt>expressionI</tt> : an expression (any type is allowed).</li>
11870</ul>
11871</li>
11872<li>Return Value:
11873<ul>
11874
11875<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
11876<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value</li>
11877<li><tt>NaN</tt> value of type <tt>double</tt> if <tt>argument1</tt> = <tt>argument2</tt></li>
11878<li>a value of the first argument otherwise</li>
11879</ul>
11880</li>
11881<li>
11882
11883<p>Example:</p>
11884
11885<div>
11886<div>
11887<pre class="source">{
11888 &quot;a&quot;: to_string(nan_if(&quot;asterixdb&quot;, &quot;asterixdb&quot;)),
11889 &quot;b&quot;: nan_if(1, 2)
11890};
11891</pre></div></div>
11892</li>
11893<li>
11894
11895<p>The expected result is:</p>
11896
11897<div>
11898<div>
11899<pre class="source">{ &quot;a&quot;: &quot;NaN&quot;, &quot;b&quot;: 1 }
11900</pre></div></div>
11901</li>
11902</ul>
11903<p>The function has an alias <tt>nanif</tt>.</p></div>
11904<div class="section">
11905<h3><a name="posinf_if_.28posinfif.29"></a>posinf_if (posinfif)</h3>
11906<ul>
11907
11908<li>
11909
11910<p>Syntax:</p>
11911
11912<div>
11913<div>
11914<pre class="source">posinf_if(expression1, expression2)
11915</pre></div></div>
11916</li>
11917<li>
11918
11919<p>Compares two arguments and returns <tt>+INF</tt> value if they are equal, otherwise returns the first argument.</p>
11920</li>
11921<li>Arguments:
11922<ul>
11923
11924<li><tt>expressionI</tt> : an expression (any type is allowed).</li>
11925</ul>
11926</li>
11927<li>Return Value:
11928<ul>
11929
11930<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
11931<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value</li>
11932<li><tt>+INF</tt> value of type <tt>double</tt> if <tt>argument1</tt> = <tt>argument2</tt></li>
11933<li>a value of the first argument otherwise</li>
11934</ul>
11935</li>
11936<li>
11937
11938<p>Example:</p>
11939
11940<div>
11941<div>
11942<pre class="source">{
11943 &quot;a&quot;: to_string(posinf_if(&quot;asterixdb&quot;, &quot;asterixdb&quot;)),
11944 &quot;b&quot;: posinf_if(1, 2)
11945};
11946</pre></div></div>
11947</li>
11948<li>
11949
11950<p>The expected result is:</p>
11951
11952<div>
11953<div>
11954<pre class="source">{ &quot;a&quot;: &quot;+INF&quot;, &quot;b&quot;: 1 }
11955</pre></div></div>
11956</li>
11957</ul>
11958<p>The function has an alias <tt>posinfif</tt>.</p></div>
11959<div class="section">
11960<h3><a name="neginf_if_.28neginfif.29"></a>neginf_if (neginfif)</h3>
11961<ul>
11962
11963<li>
11964
11965<p>Syntax:</p>
11966
11967<div>
11968<div>
11969<pre class="source">neginf_if(expression1, expression2)
11970</pre></div></div>
11971</li>
11972<li>
11973
11974<p>Compares two arguments and returns <tt>-INF</tt> value if they are equal, otherwise returns the first argument.</p>
11975</li>
11976<li>Arguments:
11977<ul>
11978
11979<li><tt>expressionI</tt> : an expression (any type is allowed).</li>
11980</ul>
11981</li>
11982<li>Return Value:
11983<ul>
11984
11985<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
11986<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value</li>
11987<li><tt>-INF</tt> value of type <tt>double</tt> if <tt>argument1</tt> = <tt>argument2</tt></li>
11988<li>a value of the first argument otherwise</li>
11989</ul>
11990</li>
11991<li>
11992
11993<p>Example:</p>
11994
11995<div>
11996<div>
11997<pre class="source">{
11998 &quot;a&quot;: to_string(neginf_if(&quot;asterixdb&quot;, &quot;asterixdb&quot;)),
11999 &quot;b&quot;: neginf_if(1, 2)
12000};
12001</pre></div></div>
12002</li>
12003<li>
12004
12005<p>The expected result is:</p>
12006
12007<div>
12008<div>
12009<pre class="source">{ &quot;a&quot;: &quot;-INF&quot;, &quot;b&quot;: 1 }
12010</pre></div></div>
12011</li>
12012</ul>
12013<p>The function has an alias <tt>neginfif</tt>.</p><!--
12014 ! Licensed to the Apache Software Foundation (ASF) under one
12015 ! or more contributor license agreements. See the NOTICE file
12016 ! distributed with this work for additional information
12017 ! regarding copyright ownership. The ASF licenses this file
12018 ! to you under the Apache License, Version 2.0 (the
12019 ! "License"); you may not use this file except in compliance
12020 ! with the License. You may obtain a copy of the License at
12021 !
12022 ! http://www.apache.org/licenses/LICENSE-2.0
12023 !
12024 ! Unless required by applicable law or agreed to in writing,
12025 ! software distributed under the License is distributed on an
12026 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
12027 ! KIND, either express or implied. See the License for the
12028 ! specific language governing permissions and limitations
12029 ! under the License.
12030 !-->
12031</div></div>
12032<div class="section">
12033<h2><a name="Miscellaneous_Functions"></a><a name="MiscFunctions" id="MiscFunctions">Miscellaneous Functions</a></h2>
12034<div class="section">
12035<h3><a name="uuid"></a>uuid</h3>
12036<ul>
12037
12038<li>
12039
12040<p>Syntax:</p>
12041
12042<div>
12043<div>
12044<pre class="source">uuid()
12045</pre></div></div>
12046</li>
12047<li>
12048
12049<p>Generates a <tt>uuid</tt>.</p>
12050</li>
12051<li>Arguments:
12052<ul>
12053
12054<li>none</li>
12055</ul>
12056</li>
12057<li>Return Value:
12058<ul>
12059
12060<li>a generated, random <tt>uuid</tt>.</li>
12061</ul>
12062</li>
12063</ul></div>
12064<div class="section">
12065<h3><a name="len"></a>len</h3>
12066<ul>
12067
12068<li>
12069
12070<p>Syntax:</p>
12071<p>len(array)</p>
12072</li>
12073<li>
12074
12075<p>Returns the length of the array array.</p>
12076</li>
12077<li>Arguments:
12078<ul>
12079
12080<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>
12081</ul>
12082</li>
12083<li>Return Value:
12084<ul>
12085
12086<li>an <tt>integer</tt> that represents the length of input array or the size of the input multiset,</li>
12087<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
12088<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value.</li>
12089</ul>
12090</li>
12091<li>
12092
12093<p>Example:</p>
12094
12095<div>
12096<div>
12097<pre class="source">len([&quot;Hello&quot;, &quot;World&quot;])
12098</pre></div></div>
12099</li>
12100<li>
12101
12102<p>The expected result is:</p>
12103
12104<div>
12105<div>
12106<pre class="source">2
12107</pre></div></div>
12108</li>
12109</ul></div>
12110<div class="section">
12111<h3><a name="not"></a>not</h3>
12112<ul>
12113
12114<li>
12115
12116<p>Syntax:</p>
12117
12118<div>
12119<div>
12120<pre class="source">not(expr)
12121</pre></div></div>
12122</li>
12123<li>
12124
12125<p>Inverts a <tt>boolean</tt> value</p>
12126</li>
12127<li>Arguments:
12128<ul>
12129
12130<li><tt>expr</tt> : an expression</li>
12131</ul>
12132</li>
12133<li>Return Value:
12134<ul>
12135
12136<li>a <tt>boolean</tt>, the inverse of <tt>expr</tt>,</li>
12137<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
12138<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value,</li>
12139<li>other non-boolean argument value will cause a type error.</li>
12140</ul>
12141</li>
12142<li>Example:
12143
12144<div>
12145<div>
12146<pre class="source">{ &quot;v1&quot;: `not`(true), &quot;v2&quot;: `not`(false), &quot;v3&quot;: `not`(null), &quot;v4&quot;: `not`(missing) };
12147</pre></div></div>
12148</li>
12149<li>
12150
12151<p>The expected result is:</p>
12152
12153<div>
12154<div>
12155<pre class="source">{ &quot;v1&quot;: false, &quot;v2&quot;: true, &quot;v3&quot;: null }
12156</pre></div></div>
12157</li>
12158</ul></div>
12159<div class="section">
12160<h3><a name="random"></a>random</h3>
12161<ul>
12162
12163<li>
12164
12165<p>Syntax:</p>
12166
12167<div>
12168<div>
12169<pre class="source">random( [seed_value] )
12170</pre></div></div>
12171</li>
12172<li>
12173
12174<p>Returns a random number, accepting an optional seed value</p>
12175</li>
12176<li>Arguments:
12177<ul>
12178
12179<li><tt>seed_value</tt>: an optional <tt>tinyint</tt>/<tt>smallint</tt>/<tt>integer</tt>/<tt>bigint</tt>/<tt>float</tt>/<tt>double</tt> value representing the seed number.</li>
12180</ul>
12181</li>
12182<li>Return Value:
12183<ul>
12184
12185<li>A random number of type <tt>double</tt> between 0 and 1,</li>
12186<li><tt>missing</tt> if the argument is a <tt>missing</tt> value,</li>
12187<li><tt>null</tt> if the argument is a <tt>null</tt> value or a non-numeric value.</li>
12188</ul>
12189</li>
12190<li>
12191
12192<p>Example:</p>
12193
12194<div>
12195<div>
12196<pre class="source">{
12197 &quot;v1&quot;: random(),
12198 &quot;v2&quot;: random(unix_time_from_datetime_in_ms(current_datetime()))
12199};
12200</pre></div></div>
12201</li>
12202</ul></div>
12203<div class="section">
12204<h3><a name="range"></a>range</h3>
12205<ul>
12206
12207<li>
12208
12209<p>Syntax:</p>
12210
12211<div>
12212<div>
12213<pre class="source">range(start_numeric_value, end_numeric_value)
12214</pre></div></div>
12215</li>
12216<li>
12217
12218<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>
12219</li>
12220<li>Arguments:</li>
12221<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>
12222<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>
12223<li>Return Value:
12224<ul>
12225
12226<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>
12227</ul>
12228</li>
12229<li>Example:
12230
12231<div>
12232<div>
12233<pre class="source">range(0, 3);
12234</pre></div></div>
12235</li>
12236<li>
12237
12238<p>The expected result is:</p>
12239
12240<div>
12241<div>
12242<pre class="source">[ 0, 1, 2, 3 ]
12243</pre></div></div>
12244</li>
12245</ul></div>
12246<div class="section">
12247<h3><a name="switch_case"></a>switch_case</h3>
12248<ul>
12249
12250<li>
12251
12252<p>Syntax:</p>
12253
12254<div>
12255<div>
12256<pre class="source">switch_case(
12257 condition,
12258 case1, case1_result,
12259 case2, case2_result,
12260 ...,
12261 default, default_result
12262)
12263</pre></div></div>
12264</li>
12265<li>
12266
12267<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>
12268</li>
12269<li>Arguments:
12270<ul>
12271
12272<li><tt>condition</tt>: a variable (any type is allowed).</li>
12273<li><tt>caseI/default</tt>: a variable (any type is allowed).</li>
12274<li><tt>caseI/default_result</tt>: a variable (any type is allowed).</li>
12275</ul>
12276</li>
12277<li>Return Value:
12278<ul>
12279
12280<li><tt>caseI_result</tt> if <tt>condition</tt> matches <tt>caseI</tt>, otherwise <tt>default_result</tt>.</li>
12281</ul>
12282</li>
12283<li>Example 1:
12284
12285<div>
12286<div>
12287<pre class="source">switch_case(
12288 &quot;a&quot;,
12289 &quot;a&quot;, 0,
12290 &quot;x&quot;, 1,
12291 &quot;y&quot;, 2,
12292 &quot;z&quot;, 3
12293);
12294</pre></div></div>
12295</li>
12296<li>
12297
12298<p>The expected result is:</p>
12299
12300<div>
12301<div>
12302<pre class="source">0
12303</pre></div></div>
12304</li>
12305<li>
12306
12307<p>Example 2:</p>
12308
12309<div>
12310<div>
12311<pre class="source">switch_case(
12312 &quot;a&quot;,
12313 &quot;x&quot;, 1,
12314 &quot;y&quot;, 2,
12315 &quot;z&quot;, 3
12316);
12317</pre></div></div>
12318</li>
12319<li>
12320
12321<p>The expected result is:</p>
12322
12323<div>
12324<div>
12325<pre class="source">3
12326</pre></div></div>
12327</li>
12328</ul></div>
12329<div class="section">
12330<h3><a name="deep_equal"></a>deep_equal</h3>
12331<ul>
12332
12333<li>
12334
12335<p>Syntax:</p>
12336
12337<div>
12338<div>
12339<pre class="source">deep_equal(expr1, expr2)
12340</pre></div></div>
12341</li>
12342<li>
12343
12344<p>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.</p>
12345</li>
12346<li>Arguments:
12347<ul>
12348
12349<li><tt>expr1</tt> : an expression,</li>
12350<li><tt>expr2</tt> : an expression.</li>
12351</ul>
12352</li>
12353<li>Return Value:
12354<ul>
12355
12356<li><tt>true</tt> or <tt>false</tt> depending on the data equality,</li>
12357<li><tt>missing</tt> if any argument is a <tt>missing</tt> value,</li>
12358<li><tt>null</tt> if any argument is a <tt>null</tt> value but no argument is a <tt>missing</tt> value.</li>
12359</ul>
12360</li>
12361<li>
12362
12363<p>Example:</p>
12364
12365<div>
12366<div>
12367<pre class="source">deep_equal(
12368 {
12369 &quot;id&quot;:1,
12370 &quot;project&quot;:&quot;AsterixDB&quot;,
12371 &quot;address&quot;:{&quot;city&quot;:&quot;Irvine&quot;, &quot;state&quot;:&quot;CA&quot;},
12372 &quot;related&quot;:[&quot;Hivestrix&quot;, &quot;Preglix&quot;, &quot;Apache VXQuery&quot;]
12373 },
12374 {
12375 &quot;id&quot;:1,
12376 &quot;project&quot;:&quot;AsterixDB&quot;,
12377 &quot;address&quot;:{&quot;city&quot;:&quot;San Diego&quot;, &quot;state&quot;:&quot;CA&quot;},
12378 &quot;related&quot;:[&quot;Hivestrix&quot;, &quot;Preglix&quot;, &quot;Apache VXQuery&quot;]
12379 }
12380);
12381</pre></div></div>
12382</li>
12383<li>
12384
12385<p>The expected result is:</p>
12386
12387<div>
12388<div>
12389<pre class="source">false
12390</pre></div></div>
12391</li>
12392</ul><!--
12393 ! Licensed to the Apache Software Foundation (ASF) under one
12394 ! or more contributor license agreements. See the NOTICE file
12395 ! distributed with this work for additional information
12396 ! regarding copyright ownership. The ASF licenses this file
12397 ! to you under the Apache License, Version 2.0 (the
12398 ! "License"); you may not use this file except in compliance
12399 ! with the License. You may obtain a copy of the License at
12400 !
12401 ! http://www.apache.org/licenses/LICENSE-2.0
12402 !
12403 ! Unless required by applicable law or agreed to in writing,
12404 ! software distributed under the License is distributed on an
12405 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
12406 ! KIND, either express or implied. See the License for the
12407 ! specific language governing permissions and limitations
12408 ! under the License.
12409 !-->
12410</div></div>
12411<div class="section">
12412<h2><a name="Bitwise_Functions"></a><a name="BitwiseFunctions" id="BitwiseFunctions">Bitwise Functions</a></h2>
12413<p>All Bit/Binary functions can only operate on 64-bit signed integers.</p>
12414<p><b>Note:</b> All non-integer numbers and other data types result in null.</p>
12415<p><b>Note:</b> The query language uses two&#x2019;s complement representation.</p>
12416<p>When looking at the value in binary form, bit 1 is the Least Significant Bit (LSB) and bit 32 is the Most Significant Bit (MSB).</p>
12417<p>(MSB) Bit 32 &#x2192; <tt>0000 0000 0000 0000 0000 0000 0000 0000</tt> &#x2190; Bit 1 (LSB)</p>
12418<div class="section">
12419<h3><a name="bitand"></a>bitand</h3>
12420<ul>
12421
12422<li>
12423
12424<p>Syntax:</p>
12425
12426<div>
12427<div>
12428<pre class="source">BITAND(int_value1, int_value2, ... , int_valueN)
12429</pre></div></div>
12430</li>
12431<li>
12432
12433<p>Returns the result of a bitwise AND operation performed on all input integer values.</p>
12434<p>The bitwise AND operation compares each bit of <tt>int_value1</tt> to the corresponding bit of every other <tt>int_value</tt>. If all bits are 1, then the corresponding result bit is set to 1; otherwise it is set to 0 (zero).</p>
12435</li>
12436<li>
12437
12438<p>Arguments:</p>
12439<ul>
12440
12441<li><tt>int_valueI</tt>: Integers, or any valid expressions which evaluate to integers, that are used to compare.</li>
12442</ul>
12443</li>
12444<li>
12445
12446<p>Return Value:</p>
12447<ul>
12448
12449<li>An integer, representing the bitwise AND between all of the input integers.</li>
12450</ul>
12451</li>
12452<li>
12453
12454<p>Limitations:</p>
12455<ul>
12456
12457<li>Input values must be integers (such as 1 or 1.0) and cannot contain decimals (such as 1.2).</li>
12458</ul>
12459</li>
12460<li>
12461
12462<p>Example 1:</p>
12463<p>Compare 3 (0011 in binary) and 6 (0110 in binary).</p>
12464
12465<div>
12466<div>
12467<pre class="source">{ &quot;BitAND&quot;: BITAND(3,6) };
12468</pre></div></div>
12469</li>
12470<li>
12471
12472<p>The expected result is:</p>
12473
12474<div>
12475<div>
12476<pre class="source">{ &quot;BitAND&quot;: 2 }
12477</pre></div></div>
12478
12479<p>This results in 2 (0010 in binary) because only bit 2 is set in both 3 (00<b>1</b>1) and 6 (01<b>1</b>0).</p>
12480</li>
12481<li>
12482
12483<p>Example 2:</p>
12484<p>Compare 4.5 and 3 (0011 in binary).</p>
12485
12486<div>
12487<div>
12488<pre class="source">{ &quot;BitAND&quot;: BITAND(4.5,3) };
12489</pre></div></div>
12490</li>
12491<li>
12492
12493<p>The expected result is:</p>
12494
12495<div>
12496<div>
12497<pre class="source">{ &quot;BitAND&quot;: null }
12498</pre></div></div>
12499
12500<p>The result is null because 4.5 is not an integer.</p>
12501</li>
12502<li>
12503
12504<p>Example 3:</p>
12505<p>Compare 4.0 (0100 in binary) and 3 (0011 in binary).</p>
12506
12507<div>
12508<div>
12509<pre class="source">{ &quot;BitAND&quot;: BITAND(4.0,3) };
12510</pre></div></div>
12511</li>
12512<li>
12513
12514<p>The expected result is:</p>
12515
12516<div>
12517<div>
12518<pre class="source">{ &quot;BitAND&quot;: 0 }
12519</pre></div></div>
12520
12521<p>This results in 0 (zero) because 4.0 (0100) and 3 (0011) do not share any bits that are both 1.</p>
12522</li>
12523<li>
12524
12525<p>Example 4:</p>
12526<p>Compare 3 (0011 in binary) and 6 (0110 in binary) and 15 (1111 in binary).</p>
12527
12528<div>
12529<div>
12530<pre class="source">{ &quot;BitAND&quot;: BITAND(3,6,15) };
12531</pre></div></div>
12532</li>
12533<li>
12534
12535<p>The expected result is:</p>
12536
12537<div>
12538<div>
12539<pre class="source">{ &quot;BitAND&quot;: 2 }
12540</pre></div></div>
12541
12542<p>This results in 2 (0010 in binary) because only the 2nd bit from the right is 1 in all three numbers.</p>
12543</li>
12544</ul></div>
12545<div class="section">
12546<h3><a name="bitclear"></a>bitclear</h3>
12547<ul>
12548
12549<li>
12550
12551<p>Syntax:</p>
12552
12553<div>
12554<div>
12555<pre class="source">BITCLEAR(int_value, positions)
12556</pre></div></div>
12557</li>
12558<li>
12559
12560<p>Returns the result after clearing the specified bit, or array of bits in <tt>int_value</tt> using the given <tt>positions</tt>.</p>
12561<p><b>Note:</b> Specifying a negative or zero bit position makes the function return a null.</p>
12562</li>
12563<li>
12564
12565<p>Arguments:</p>
12566<ul>
12567
12568<li>
12569
12570<p><tt>int_value</tt>: An integer, or any valid expression which evaluates to an integer, that contains the target bit or bits to clear.</p>
12571</li>
12572<li>
12573
12574<p><tt>positions</tt>: An integer or an array of integers specifying the position or positions to be cleared.</p>
12575</li>
12576</ul>
12577</li>
12578<li>
12579
12580<p>Return Value:</p>
12581<ul>
12582
12583<li>An integer, representing the result after clearing the bit or bits specified.</li>
12584</ul>
12585</li>
12586<li>
12587
12588<p>Limitations:</p>
12589<ul>
12590
12591<li>Input values must be integers (such as 1 or 1.0) and cannot contain decimals (such as 1.2).</li>
12592</ul>
12593</li>
12594<li>
12595
12596<p>Example 1:</p>
12597<p>Clear bit 1 from 6 (0110 in binary).</p>
12598
12599<div>
12600<div>
12601<pre class="source">{ &quot;BitCLEAR&quot;: BITCLEAR(6,1) };
12602</pre></div></div>
12603</li>
12604<li>
12605
12606<p>The expected result is:</p>
12607
12608<div>
12609<div>
12610<pre class="source">{ &quot;BitCLEAR&quot;: 6 }
12611</pre></div></div>
12612
12613<p>This results in 6 (011<b>0</b> in binary) because bit 1 was already zero.</p>
12614</li>
12615<li>
12616
12617<p>Example 2:</p>
12618<p>Clear bits 1 and 2 from 6 (01<b>10</b> in binary).</p>
12619
12620<div>
12621<div>
12622<pre class="source">{ &quot;BitCLEAR&quot;: BITCLEAR(6,[1,2]) };
12623</pre></div></div>
12624</li>
12625<li>
12626
12627<p>The expected result is:</p>
12628
12629<div>
12630<div>
12631<pre class="source">{ &quot;BitCLEAR&quot;: 4 }
12632</pre></div></div>
12633
12634<p>This results in 4 (01<b>0</b>0 in binary) because bit 2 changed to zero.</p>
12635</li>
12636<li>
12637
12638<p>Example 3:</p>
12639<p>Clear bits 1, 2, 4, and 5 from 31 (0<b>11</b>1<b>11</b> in binary).</p>
12640
12641<div>
12642<div>
12643<pre class="source">{ &quot;BitCLEAR&quot;: BITCLEAR(31,[1,2,4,5]) };
12644</pre></div></div>
12645</li>
12646<li>
12647
12648<p>The expected result is:</p>
12649
12650<div>
12651<div>
12652<pre class="source">{ &quot;BitCLEAR&quot;: 4 }
12653</pre></div></div>
12654
12655<p>This results in 4 (0<b>00</b>1<b>00</b>) because bits 1, 2, 4, and 5 changed to zero.</p>
12656</li>
12657</ul></div>
12658<div class="section">
12659<h3><a name="bitnot"></a>bitnot</h3>
12660<ul>
12661
12662<li>
12663
12664<p>Syntax:</p>
12665
12666<div>
12667<div>
12668<pre class="source">BITNOT(int_value)
12669</pre></div></div>
12670</li>
12671<li>
12672
12673<p>Returns the results of a bitwise logical NOT operation performed on an integer value.</p>
12674<p>The bitwise logical NOT operation reverses the bits in the value. For each value bit that is 1, the corresponding result bit will be set to 0 (zero); and for each value bit that is 0 (zero), the corresponding result bit will be set to 1.</p>
12675<p><b>Note:</b> All bits of the integer will be altered by this operation.</p>
12676</li>
12677<li>
12678
12679<p>Arguments:</p>
12680<ul>
12681
12682<li><tt>int_value</tt>: An integer, or any valid expression which evaluates to an integer, that contains the target bits to reverse.</li>
12683</ul>
12684</li>
12685<li>
12686
12687<p>Return Value:</p>
12688<ul>
12689
12690<li>An integer, representing the result after performing the logical NOT operation.</li>
12691</ul>
12692</li>
12693<li>
12694
12695<p>Limitations:</p>
12696<ul>
12697
12698<li>Input values must be integers (such as 1 or 1.0) and cannot contain decimals (such as 1.2).</li>
12699</ul>
12700</li>
12701<li>
12702
12703<p>Example 1:</p>
12704<p>Perform the NOT operation on 3 (0000 0000 0000 0000 0000 0000 0000 0011 in binary).</p>
12705
12706<div>
12707<div>
12708<pre class="source">{ &quot;BitNOT&quot;: BITNOT(3) };
12709</pre></div></div>
12710</li>
12711<li>
12712
12713<p>The expected result is:</p>
12714
12715<div>
12716<div>
12717<pre class="source">{ &quot;BitNOT&quot;: -4 }
12718</pre></div></div>
12719
12720<p>This results in -4 (<b>1111 1111 1111 1111 1111 1111 1111 1100</b> in binary) because all bits changed.</p>
12721</li>
12722</ul></div>
12723<div class="section">
12724<h3><a name="bitor"></a>bitor</h3>
12725<ul>
12726
12727<li>
12728
12729<p>Syntax:</p>
12730
12731<div>
12732<div>
12733<pre class="source">BITOR(int_value1, int_value2, ... , int_valueN)
12734</pre></div></div>
12735</li>
12736<li>
12737
12738<p>Returns the result of a bitwise inclusive OR operation performed on all input integer values.</p>
12739<p>The bitwise inclusive OR operation compares each bit of <tt>int_value1</tt> to the corresponding bit of every other <tt>int_value</tt>. If any bit is 1, the corresponding result bit is set to 1; otherwise, it is set to 0 (zero).</p>
12740</li>
12741<li>
12742
12743<p>Arguments:</p>
12744<ul>
12745
12746<li><tt>int_valueI</tt>: Integers, or any valid expressions which evaluate to integers, that are used to compare.</li>
12747</ul>
12748</li>
12749<li>
12750
12751<p>Return Value:</p>
12752<ul>
12753
12754<li>An integer, representing the bitwise OR between all of the input integers.</li>
12755</ul>
12756</li>
12757<li>
12758
12759<p>Limitations:</p>
12760<ul>
12761
12762<li>Input values must be integers (such as 1 or 1.0) and cannot contain decimals (such as 1.2).</li>
12763</ul>
12764</li>
12765<li>
12766
12767<p>Example 1:</p>
12768<p>Perform OR on 3 (0011 in binary) and 6 (0110 in binary).</p>
12769
12770<div>
12771<div>
12772<pre class="source">{ &quot;BitOR&quot;: BITOR(3,6) };
12773</pre></div></div>
12774</li>
12775<li>
12776
12777<p>The expected result is:</p>
12778
12779<div>
12780<div>
12781<pre class="source">{ &quot;BitOR&quot;: 7 }
12782</pre></div></div>
12783
12784<p>This results in 7 (0<b>111</b> in binary) because at least 1 bit of each (00<b>11</b> and 0<b>11</b>0) is 1 in bits 1, 2, and 3.</p>
12785</li>
12786<li>
12787
12788<p>Example 2:</p>
12789<p>Perform OR on 3 (0011 in binary) and -4 (1000 0000 0000 &#x2026; 0000 1100 in binary).</p>
12790
12791<div>
12792<div>
12793<pre class="source">{ &quot;BitOR&quot;: BITOR(3,-4) };
12794</pre></div></div>
12795</li>
12796<li>
12797
12798<p>The expected result is:</p>
12799
12800<div>
12801<div>
12802<pre class="source">{ &quot;BitOR&quot;: -1 }
12803</pre></div></div>
12804
12805<p>This results in -1 (<b>1111 1111 1111 &#x2026; 1111 1111</b> in binary) because the two 1 bits in 3 fill in the two 0 bits in -4 to turn on all the bits.</p>
12806</li>
12807<li>
12808
12809<p>Example 3:</p>
12810<p>Perform OR on 3 (0011 in binary) and 6 (0110 in binary) and 15 (1111 in binary).</p>
12811
12812<div>
12813<div>
12814<pre class="source">{ &quot;BitOR&quot;: BITOR(3,6,15) };
12815</pre></div></div>
12816</li>
12817<li>
12818
12819<p>The expected result is:</p>
12820
12821<div>
12822<div>
12823<pre class="source">{ &quot;BitOR&quot;: 15 }
12824</pre></div></div>
12825
12826<p>This results in 15 (1111 in binary) because there is at least one 1 in each of the four rightmost bits.</p>
12827</li>
12828</ul></div>
12829<div class="section">
12830<h3><a name="bitset"></a>bitset</h3>
12831<ul>
12832
12833<li>
12834
12835<p>Syntax:</p>
12836
12837<div>
12838<div>
12839<pre class="source">BITSET(int_value, positions)
12840</pre></div></div>
12841</li>
12842<li>
12843
12844<p>Returns the result after setting the specified bit <tt>position</tt>, or array of bit positions, to 1 in the given <tt>int_value</tt>.</p>
12845<p><b>Note:</b> Specifying a negative or zero position makes the function return a null.</p>
12846</li>
12847<li>
12848
12849<p>Arguments:</p>
12850<ul>
12851
12852<li>
12853
12854<p><tt>int_value</tt>: An integer, or any valid expression which evaluates to an integer, that contains the target bit or bits to set.</p>
12855</li>
12856<li>
12857
12858<p><tt>positions</tt>: An integer or an array of integers specifying the position or positions to be set.</p>
12859</li>
12860</ul>
12861</li>
12862<li>
12863
12864<p>Return Value:</p>
12865<ul>
12866
12867<li>An integer, representing the result after setting the bit or bits specified. If the bit is already set, then it stays set.</li>
12868</ul>
12869</li>
12870<li>
12871
12872<p>Limitations:</p>
12873<ul>
12874
12875<li>Input values must be integers (such as 1 or 1.0) and cannot contain decimals (such as 1.2).</li>
12876</ul>
12877</li>
12878<li>
12879
12880<p>Example 1:</p>
12881<p>Set bit 1 in the value 6 (011<b>0</b> in binary).</p>
12882
12883<div>
12884<div>
12885<pre class="source">{ &quot;BitSET&quot;: BITSET(6,1) };
12886</pre></div></div>
12887</li>
12888<li>
12889
12890<p>The expected result is:</p>
12891
12892<div>
12893<div>
12894<pre class="source">{ &quot;BitSET&quot;: 7 }
12895</pre></div></div>
12896
12897<p>This results in 7 (011<b>1</b> in binary) because bit 1 changed to 1.</p>
12898</li>
12899<li>
12900
12901<p>Example 2:</p>
12902<p>Set bits 1 and 2 in the value 6 (01<b>10</b> in binary).</p>
12903
12904<div>
12905<div>
12906<pre class="source">{ &quot;BitSET&quot;: BITSET(6,[1,2]) };
12907</pre></div></div>
12908</li>
12909<li>
12910
12911<p>The expected result is:</p>
12912
12913<div>
12914<div>
12915<pre class="source">{ &quot;BitSET&quot;: 7 }
12916</pre></div></div>
12917
12918<p>This also results in 7 (01<b>11</b> in binary) because bit 1 changed while bit 2 remained the same.</p>
12919</li>
12920<li>
12921
12922<p>Example 3:</p>
12923<p>Set bits 1 and 4 in the value 6 (<b>0</b>11<b>0</b> in binary).</p>
12924
12925<div>
12926<div>
12927<pre class="source">{ &quot;BitSET&quot;: BITSET(6,[1,4]) };
12928</pre></div></div>
12929</li>
12930<li>
12931
12932<p>The expected result is:</p>
12933
12934<div>
12935<div>
12936<pre class="source">{ &quot;BitSET&quot;: 15 }
12937</pre></div></div>
12938
12939<p>This results in 15 (<b>1</b>11<b>1</b> in binary) because bit 1 and 4 changed to ones.</p>
12940</li>
12941</ul></div>
12942<div class="section">
12943<h3><a name="bitshift"></a>bitshift</h3>
12944<ul>
12945
12946<li>
12947
12948<p>Syntax:</p>
12949
12950<div>
12951<div>
12952<pre class="source">BITSHIFT(int_value, shift_amount[, rotate])
12953</pre></div></div>
12954</li>
12955<li>
12956
12957<p>Returns the result of a bit shift operation performed on the integer value <tt>int_value</tt>. The <tt>shift_amount</tt> supports left and right shifts. These are logical shifts. The third parameter <tt>rotate</tt> supports circular shift. This is similar to the BitROTATE function in Oracle.</p>
12958</li>
12959<li>
12960
12961<p>Arguments:</p>
12962<ul>
12963
12964<li>
12965
12966<p><tt>int_value</tt>: An integer, or any valid expression which evaluates to an integer, that contains the target bit or bits to shift.</p>
12967</li>
12968<li>
12969
12970<p><tt>shift_amount</tt>: An integer, or any valid expression which evaluates to an integer, that contains the number of bits to shift.</p>
12971<ul>
12972
12973<li>
12974
12975<p>A positive (+) number means this is a LEFT shift.</p>
12976</li>
12977<li>
12978
12979<p>A negative (-) number means this is a RIGHT shift.</p>
12980</li>
12981</ul>
12982</li>
12983<li>
12984
12985<p><tt>rotate</tt>: (Optional) A boolean, or any valid expression which evaluates to a boolean, where:</p>
12986<ul>
12987
12988<li>
12989
12990<p>FALSE means this is a LOGICAL shift, where bits shifted off the end of a value are considered lost.</p>
12991</li>
12992<li>
12993
12994<p>TRUE means this is a CIRCULAR shift (shift-and-rotate operation), where bits shifted off the end of a value are rotated back onto the value at the <i>other</i> end. In other words, the bits rotate in what might be thought of as a circular pattern; therefore, these bits are not lost.</p>
12995</li>
12996</ul>
12997<p>If omitted, the default is FALSE.</p>
12998</li>
12999</ul>
13000<p>For comparison, see the below table.</p>
13001<table border="0" class="table table-striped">
13002<thead>
13003
13004<tr class="a">
13005<th> Input </th>
13006<th> Shift </th>
13007<th> Result of Logical Shift (Rotate FALSE) </th>
13008<th> Result of Circular Shift (Rotate TRUE) </th></tr>
13009</thead><tbody>
13010
13011<tr class="b">
13012<td> 6 (0000 0110) </td>
13013<td> 4 </td>
13014<td> 96 (0110 0000) </td>
13015<td> 96 (0110 0000) </td></tr>
13016<tr class="a">
13017<td> 6 (0000 0110) </td>
13018<td> 3 </td>
13019<td> 48 (0011 0000) </td>
13020<td> 48 (0011 0000) </td></tr>
13021<tr class="b">
13022<td> 6 (0000 0110) </td>
13023<td> 2 </td>
13024<td> 24 (0001 1000) </td>
13025<td> 24 (0001 1000) </td></tr>
13026<tr class="a">
13027<td> 6 (0000 0110) </td>
13028<td> 1 </td>
13029<td> 12 (0000 1100) </td>
13030<td> 12 (0000 1100) </td></tr>
13031<tr class="b">
13032<td> <b>6 (0000 0110)</b> </td>
13033<td> <b>0</b> </td>
13034<td> <b>6 (0000 0110)</b> </td>
13035<td> <b>6 (0000 0110)</b> </td></tr>
13036<tr class="a">
13037<td> 6 (0000 0110) </td>
13038<td> -1 </td>
13039<td> 3 (0000 0011) </td>
13040<td> 3 (0000 0011) </td></tr>
13041<tr class="b">
13042<td> 6 (0000 0110) </td>
13043<td> -2 </td>
13044<td> 1 (0000 0001) </td>
13045<td> -9223372036854775807 (1000 0000 &#x2026; 0000 0001) </td></tr>
13046<tr class="a">
13047<td> 6 (0000 0110) </td>
13048<td> -3 </td>
13049<td> 0 (0000 0000) </td>
13050<td> -4611686018427387904 (1100 0000 &#x2026; 0000 0000) </td></tr>
13051<tr class="b">
13052<td> 6 (0000 0110) </td>
13053<td> -4 </td>
13054<td> 0 (0000 0000) </td>
13055<td> 6917529027641081856 (0110 0000 &#x2026; 0000 0000) </td></tr>
13056</tbody>
13057</table>
13058</li>
13059<li>
13060
13061<p>Return Value:</p>
13062<ul>
13063
13064<li>An integer, representing the result of either a logical or circular shift of the given integer.</li>
13065</ul>
13066</li>
13067<li>
13068
13069<p>Limitations:</p>
13070<ul>
13071
13072<li>Input values must be integers (such as 1 or 1.0) and cannot contain decimals (such as 1.2).</li>
13073</ul>
13074</li>
13075<li>
13076
13077<p>Example 1:</p>
13078<p>Logical left shift of the number 6 (0110 in binary) by one bit.</p>
13079
13080<div>
13081<div>
13082<pre class="source">{ &quot;BitSHIFT&quot;: BITSHIFT(6,1,FALSE) };
13083</pre></div></div>
13084</li>
13085<li>
13086
13087<p>The expected result is:</p>
13088
13089<div>
13090<div>
13091<pre class="source">{ &quot;BitSHIFT&quot;: 12 }
13092</pre></div></div>
13093
13094<p>This results in 12 (1100 in binary) because the 1-bits moved from positions 2 and 3 to positions 3 and 4.</p>
13095</li>
13096<li>
13097
13098<p>Example 2:</p>
13099<p>Logical right shift of the number 6 (0110 in binary) by two bits.</p>
13100
13101<div>
13102<div>
13103<pre class="source">{ &quot;BitSHIFT&quot;: BITSHIFT(6,-2) };
13104</pre></div></div>
13105</li>
13106<li>
13107
13108<p>The expected result is:</p>
13109
13110<div>
13111<div>
13112<pre class="source">{ &quot;BitSHIFT&quot;: 1 }
13113</pre></div></div>
13114
13115<p>This results in 1 (0001 in binary) because the 1-bit in position 3 moved to position 1 and the 1-bit in position 2 was dropped.</p>
13116</li>
13117<li>
13118
13119<p>Example 2b:</p>
13120<p>Circular right shift of the number 6 (0110 in binary) by two bits.</p>
13121
13122<div>
13123<div>
13124<pre class="source">{ &quot;BitSHIFT&quot;: BITSHIFT(6,-2,TRUE) };
13125</pre></div></div>
13126</li>
13127<li>
13128
13129<p>The expected result is:</p>
13130
13131<div>
13132<div>
13133<pre class="source">{ &quot;BitSHIFT&quot;: -9223372036854775807 }
13134</pre></div></div>
13135
13136<p>This results in -9223372036854775807 (1100 0000 0000 0000 0000 0000 0000 0000 in binary) because the two 1-bits wrapped right, around to the Most Significant Digit position and changed the integer&#x2019;s sign to negative.</p>
13137</li>
13138<li>
13139
13140<p>Example 3:</p>
13141<p>Circular left shift of the number 524288 (1000 0000 0000 0000 0000 in binary) by 45 bits.</p>
13142
13143<div>
13144<div>
13145<pre class="source">{ &quot;BitSHIFT&quot;: BITSHIFT(524288,45,TRUE) };
13146</pre></div></div>
13147</li>
13148<li>
13149
13150<p>The expected result is:</p>
13151
13152<div>
13153<div>
13154<pre class="source">{ &quot;BitSHIFT&quot;: 1 }
13155</pre></div></div>
13156
13157<p>This results in 1 because the 1-bit wrapped left, around to the Least Significant Digit position.</p>
13158</li>
13159</ul></div>
13160<div class="section">
13161<h3><a name="bittest"></a>bittest</h3>
13162<ul>
13163
13164<li>
13165
13166<p>Syntax:</p>
13167
13168<div>
13169<div>
13170<pre class="source">BITTEST(int_value, positions [, all_set])
13171</pre></div></div>
13172</li>
13173<li>
13174
13175<p>Returns TRUE if the specified bit, or bits, is a 1; otherwise, returns FALSE if the specified bit, or bits, is a 0 (zero).</p>
13176<p><b>Note:</b> Specifying a negative or zero bit position will result in null being returned.</p>
13177</li>
13178<li>
13179
13180<p>Arguments:</p>
13181<ul>
13182
13183<li>
13184
13185<p><tt>int_value</tt>: An integer, or any valid expression which evaluates to an integer, that contains the target bit or bits to test.</p>
13186</li>
13187<li>
13188
13189<p><tt>positions</tt>: An integer or an array of integers specifying the position or positions to be tested.</p>
13190</li>
13191<li>
13192
13193<p><tt>all_set</tt>: (Optional) A boolean, or any valid expression which evaluates to a boolean.</p>
13194<ul>
13195
13196<li>
13197
13198<p>When <tt>all_set</tt> is FALSE, then it returns TRUE even if one bit in one of the positions is set.</p>
13199</li>
13200<li>
13201
13202<p>When <tt>all_set</tt> is TRUE, then it returns TRUE only if all input positions are set.</p>
13203</li>
13204</ul>
13205<p>If omitted, the default is FALSE.</p>
13206</li>
13207</ul>
13208</li>
13209<li>
13210
13211<p>Return Value:</p>
13212<ul>
13213
13214<li>A boolean, that follows the below table:
13215<table border="0" class="table table-striped">
13216<thead>
13217
13218<tr class="a">
13219<th> <tt>int_value</tt> </th>
13220<th> <tt>all_set</tt> </th>
13221<th> Return Value </th></tr>
13222</thead><tbody>
13223
13224<tr class="b">
13225<td> <i>all</i> specified bits are TRUE </td>
13226<td> FALSE </td>
13227<td> TRUE </td></tr>
13228<tr class="a">
13229<td> <i>all</i> specified bits are TRUE </td>
13230<td> TRUE </td>
13231<td> TRUE </td></tr>
13232<tr class="b">
13233<td> <i>some</i> specified bits are TRUE </td>
13234<td> FALSE </td>
13235<td> TRUE </td></tr>
13236<tr class="a">
13237<td> <i>some</i> specified bits are TRUE </td>
13238<td> TRUE </td>
13239<td> FALSE </td></tr>
13240</tbody>
13241</table>
13242</li>
13243</ul>
13244</li>
13245<li>
13246
13247<p>Limitations:</p>
13248<ul>
13249
13250<li>Input values must be integers (such as 1 or 1.0) and cannot contain decimals (such as 1.2).</li>
13251</ul>
13252</li>
13253<li>
13254
13255<p>Example 1:</p>
13256<p>In the number 6 (0110 in binary), is bit 1 set?</p>
13257
13258<div>
13259<div>
13260<pre class="source">{ &quot;IsBitSET&quot;: ISBITSET(6,1) };
13261</pre></div></div>
13262</li>
13263<li>
13264
13265<p>The expected result is:</p>
13266
13267<div>
13268<div>
13269<pre class="source">{ &quot;IsBitSET&quot;: false }
13270</pre></div></div>
13271
13272<p>This returns FALSE because bit 1 of 6 (011<b>0</b> in binary) is not set to 1.</p>
13273</li>
13274<li>
13275
13276<p>Example 2:</p>
13277<p>In the number 1, is either bit 1 or bit 2 set?</p>
13278
13279<div>
13280<div>
13281<pre class="source">{ &quot;BitTEST&quot;: BITTEST(1,[1,2],FALSE) };
13282</pre></div></div>
13283</li>
13284<li>
13285
13286<p>The expected result is:</p>
13287
13288<div>
13289<div>
13290<pre class="source">{ &quot;BitTEST&quot;: true }
13291</pre></div></div>
13292
13293<p>This returns TRUE because bit 1 of the number 1 (000<b>1</b> in binary) is set to 1.</p>
13294</li>
13295<li>
13296
13297<p>Example 3:</p>
13298<p>In the number 6 (0110 in binary), are both bits 2 and 3 set?</p>
13299
13300<div>
13301<div>
13302<pre class="source">{ &quot;IsBitSET&quot;: ISBITSET(6,[2,3],TRUE) };
13303</pre></div></div>
13304</li>
13305<li>
13306
13307<p>The expected result is:</p>
13308
13309<div>
13310<div>
13311<pre class="source">{ &quot;IsBitSET&quot;: true }
13312</pre></div></div>
13313
13314<p>This returns TRUE because both bits 2 and 3 in the number 6 (0<b>11</b>0 in binary) are set to 1.</p>
13315</li>
13316<li>
13317
13318<p>Example 4:</p>
13319<p>In the number 6 (0110 in binary), are all the bits in positions 1 through 3 set?</p>
13320
13321<div>
13322<div>
13323<pre class="source">{ &quot;BitTEST&quot;: BITTEST(6,[1,3],TRUE) };
13324</pre></div></div>
13325</li>
13326<li>
13327
13328<p>The expected result is:</p>
13329
13330<div>
13331<div>
13332<pre class="source">{ &quot;BitTEST&quot;: false }
13333</pre></div></div>
13334
13335<p>This returns FALSE because bit 1 in the number 6 (011<b>0</b> in binary) is set to 0 (zero).</p>
13336</li>
13337</ul>
13338<p>The function has an alias <tt>isbitset</tt>.</p></div>
13339<div class="section">
13340<h3><a name="bitxor"></a>bitxor</h3>
13341<ul>
13342
13343<li>
13344
13345<p>Syntax:</p>
13346
13347<div>
13348<div>
13349<pre class="source">BITXOR(int_value1, int_value2, ... , int_valueN)
13350</pre></div></div>
13351</li>
13352<li>
13353
13354<p>Returns the result of a bitwise Exclusive OR operation performed on two or more integer values.</p>
13355<p>The bitwise Exclusive OR operation compares each bit of <tt>int_value1</tt> to the corresponding bit of <tt>int_value2</tt>.</p>
13356<p>If there are more than two input values, the first two are compared; then their result is compared to the next input value; and so on.</p>
13357<p>When the compared bits do not match, the result bit is 1; otherwise, the compared bits do match, and the result bit is 0 (zero), as summarized:</p>
13358<table border="0" class="table table-striped">
13359<thead>
13360
13361<tr class="a">
13362<th> Bit 1 </th>
13363<th> Bit 2 </th>
13364<th> XOR Result Bit </th></tr>
13365</thead><tbody>
13366
13367<tr class="b">
13368<td> 0 </td>
13369<td> 0 </td>
13370<td> 0 </td></tr>
13371<tr class="a">
13372<td> 0 </td>
13373<td> 1 </td>
13374<td> 1 </td></tr>
13375<tr class="b">
13376<td> 1 </td>
13377<td> 0 </td>
13378<td> 1 </td></tr>
13379<tr class="a">
13380<td> 1 </td>
13381<td> 1 </td>
13382<td> 0 </td></tr>
13383</tbody>
13384</table>
13385</li>
13386<li>
13387
13388<p>Arguments:</p>
13389<ul>
13390
13391<li><tt>int_valueI</tt>: Integers, or any valid expressions which evaluate to integers, that are used to compare.</li>
13392</ul>
13393</li>
13394<li>
13395
13396<p>Return Value:</p>
13397<ul>
13398
13399<li>An integer, representing the bitwise XOR between the input integers.</li>
13400</ul>
13401</li>
13402<li>
13403
13404<p>Limitations:</p>
13405<ul>
13406
13407<li>Input values must be integers (such as 1 or 1.0) and cannot contain decimals (such as 1.2).</li>
13408</ul>
13409</li>
13410<li>
13411
13412<p>Example 1:</p>
13413<p>Perform the XOR operation on 3 (0011 in binary) and 6 (0110 in binary).</p>
13414
13415<div>
13416<div>
13417<pre class="source">{ &quot;BitXOR&quot;: BITXOR(3,6) };
13418</pre></div></div>
13419</li>
13420<li>
13421
13422<p>The expected result is:</p>
13423
13424<div>
13425<div>
13426<pre class="source">{ &quot;BitXOR&quot;: 5 }
13427</pre></div></div>
13428
13429<p>This returns 5 (0101 in binary) because the 1st bit pair and 3rd bit pair are different (resulting in 1) while the 2nd bit pair and 4th bit pair are the same (resulting in 0):</p>
13430
13431<div>
13432<div>
13433<pre class="source">0011 (3)
134340110 (6)
13435====
134360101 (5)
13437</pre></div></div>
13438</li>
13439<li>
13440
13441<p>Example 2:</p>
13442<p>Perform the XOR operation on 3 (0011 in binary) and 6 (0110 in binary) and 15 (1111 in binary).</p>
13443
13444<div>
13445<div>
13446<pre class="source">{ &quot;BitXOR&quot;: BITXOR(3,6,15) };
13447</pre></div></div>
13448</li>
13449<li>
13450
13451<p>The expected result is:</p>
13452
13453<div>
13454<div>
13455<pre class="source">{ &quot;BitXOR&quot;: 10 }
13456</pre></div></div>
13457
13458<p>This returns 10 (1010 in binary) because 3 XOR 6 equals 5 (0101 in binary), and then 5 XOR 15 equals 10 (1010 in binary).</p>
13459</li>
13460</ul><!--
13461 ! Licensed to the Apache Software Foundation (ASF) under one
13462 ! or more contributor license agreements. See the NOTICE file
13463 ! distributed with this work for additional information
13464 ! regarding copyright ownership. The ASF licenses this file
13465 ! to you under the Apache License, Version 2.0 (the
13466 ! "License"); you may not use this file except in compliance
13467 ! with the License. You may obtain a copy of the License at
13468 !
13469 ! http://www.apache.org/licenses/LICENSE-2.0
13470 !
13471 ! Unless required by applicable law or agreed to in writing,
13472 ! software distributed under the License is distributed on an
13473 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
13474 ! KIND, either express or implied. See the License for the
13475 ! specific language governing permissions and limitations
13476 ! under the License.
13477 !-->
13478</div></div>
13479<div class="section">
13480<h2><a name="Window_Functions"></a><a name="WindowFunctions" id="WindowFunctions">Window Functions</a></h2>
13481<p>Window functions are used to compute an aggregate or cumulative value, based on a portion of the tuples selected by a query. For each input tuple, a movable window of tuples is defined. The window determines the tuples to be used by the window function.</p>
13482<p>The tuples are not grouped into a single output tuple &#x2014; each tuple remains separate in the query output.</p>
13483<p>All window functions must be used with an OVER clause. Refer to <a href="manual.html#Over_clauses">Window Queries</a> for details.</p>
13484<p>Window functions cannot appear in the FROM clause clause or LIMIT clause.</p>
13485<div class="section">
13486<h3><a name="cume_dist"></a>cume_dist</h3>
13487<ul>
13488
13489<li>
13490
13491<p>Syntax:</p>
13492
13493<div>
13494<div>
13495<pre class="source">CUME_DIST() OVER ([window-partition-clause] [window-order-clause])
13496</pre></div></div>
13497</li>
13498<li>
13499
13500<p>Returns the percentile rank of the current tuple as part of the cumulative distribution &#x2013; that is, the number of tuples ranked lower than or equal to the current tuple, including the current tuple, divided by the total number of tuples in the window partition.</p>
13501<p>The window order clause determines the sort order of the tuples. If the window order clause is omitted, the function returns the same result (1.0) for each tuple.</p>
13502</li>
13503<li>
13504
13505<p>Arguments:</p>
13506<ul>
13507
13508<li>None.</li>
13509</ul>
13510</li>
13511<li>
13512
13513<p>Clauses:</p>
13514<ul>
13515
13516<li>
13517
13518<p>(Optional) <a href="manual.html#Window_partition_clause">Window Partition Clause</a>.</p>
13519</li>
13520<li>
13521
13522<p>(Optional) <a href="manual.html#Window_order_clause">Window Order Clause</a>.</p>
13523</li>
13524</ul>
13525</li>
13526<li>
13527
13528<p>Return Value:</p>
13529<ul>
13530
13531<li>A number greater than 0 and less than or equal to 1. The higher the value, the higher the ranking.</li>
13532</ul>
13533</li>
13534<li>
13535
13536<p>Example:</p>
13537<p>For each customer, find the cumulative distribution of all orders by order number.</p>
13538
13539<div>
13540<div>
13541<pre class="source">FROM orders AS o
13542SELECT o.custid, o.orderno, CUME_DIST() OVER (
13543 PARTITION BY o.custid
13544 ORDER BY o.orderno
13545) AS `rank`
13546ORDER BY o.custid, o.orderno;
13547</pre></div></div>
13548</li>
13549<li>
13550
13551<p>The expected result is:</p>
13552
13553<div>
13554<div>
13555<pre class="source">[
13556 {
13557 &quot;rank&quot;: 0.25,
13558 &quot;custid&quot;: &quot;C13&quot;,
13559 &quot;orderno&quot;: 1002
13560 },
13561 {
13562 &quot;rank&quot;: 0.5,
13563 &quot;custid&quot;: &quot;C13&quot;,
13564 &quot;orderno&quot;: 1007
13565 },
13566 {
13567 &quot;rank&quot;: 0.75,
13568 &quot;custid&quot;: &quot;C13&quot;,
13569 &quot;orderno&quot;: 1008
13570 },
13571 {
13572 &quot;rank&quot;: 1,
13573 &quot;custid&quot;: &quot;C13&quot;,
13574 &quot;orderno&quot;: 1009
13575 },
13576 {
13577 &quot;rank&quot;: 1,
13578 &quot;custid&quot;: &quot;C31&quot;,
13579 &quot;orderno&quot;: 1003
13580 },
13581 {
13582 &quot;rank&quot;: 1,
13583 &quot;custid&quot;: &quot;C35&quot;,
13584 &quot;orderno&quot;: 1004
13585 },
13586 {
13587 &quot;rank&quot;: 1,
13588 &quot;custid&quot;: &quot;C37&quot;,
13589 &quot;orderno&quot;: 1005
13590 },
13591 {
13592 &quot;rank&quot;: 0.5,
13593 &quot;custid&quot;: &quot;C41&quot;,
13594 &quot;orderno&quot;: 1001
13595 },
13596 {
13597 &quot;rank&quot;: 1,
13598 &quot;custid&quot;: &quot;C41&quot;,
13599 &quot;orderno&quot;: 1006
13600 }
13601]
13602</pre></div></div>
13603</li>
13604</ul></div>
13605<div class="section">
13606<h3><a name="dense_rank"></a>dense_rank</h3>
13607<ul>
13608
13609<li>
13610
13611<p>Syntax:</p>
13612
13613<div>
13614<div>
13615<pre class="source">DENSE_RANK() OVER ([window-partition-clause] [window-order-clause])
13616</pre></div></div>
13617</li>
13618<li>
13619
13620<p>Returns the dense rank of the current tuple &#x2013; that is, the number of distinct tuples preceding this tuple in the current window partition, plus one.</p>
13621<p>The tuples are ordered by the window order clause. If any tuples are tied, they will have the same rank. If the window order clause is omitted, the function returns the same result (1) for each tuple.</p>
13622<p>For this function, when any tuples have the same rank, the rank of the next tuple will be consecutive, so there will not be a gap in the sequence of returned values. For example, if there are five tuples ranked 3, the next dense rank is 4.</p>
13623</li>
13624<li>
13625
13626<p>Arguments:</p>
13627<ul>
13628
13629<li>None.</li>
13630</ul>
13631</li>
13632<li>
13633
13634<p>Clauses:</p>
13635<ul>
13636
13637<li>
13638
13639<p>(Optional) <a href="manual.html#Window_partition_clause">Window Partition Clause</a>.</p>
13640</li>
13641<li>
13642
13643<p>(Optional) <a href="manual.html#Window_order_clause">Window Order Clause</a>.</p>
13644</li>
13645</ul>
13646</li>
13647<li>
13648
13649<p>Return Value:</p>
13650<ul>
13651
13652<li>An integer, greater than or equal to 1.</li>
13653</ul>
13654</li>
13655<li>
13656
13657<p>Example:</p>
13658<p>Find the dense rank of all orders by number of items.</p>
13659
13660<div>
13661<div>
13662<pre class="source">FROM orders AS o
13663SELECT o.orderno, LEN(o.items) AS items,
13664DENSE_RANK() OVER (
13665 ORDER BY LEN(o.items)
13666) AS `rank`
13667ORDER BY `rank`, o.orderno;
13668</pre></div></div>
13669</li>
13670<li>
13671
13672<p>The expected result is:</p>
13673
13674<div>
13675<div>
13676<pre class="source">[
13677 {
13678 &quot;items&quot;: 0,
13679 &quot;rank&quot;: 1,
13680 &quot;orderno&quot;: 1009
13681 },
13682 {
13683 &quot;items&quot;: 1,
13684 &quot;rank&quot;: 2,
13685 &quot;orderno&quot;: 1008
13686 },
13687 {
13688 &quot;items&quot;: 2,
13689 &quot;rank&quot;: 3,
13690 &quot;orderno&quot;: 1001
13691 },
13692 {
13693 &quot;items&quot;: 2,
13694 &quot;rank&quot;: 3,
13695 &quot;orderno&quot;: 1002
13696 },
13697 {
13698 &quot;items&quot;: 2,
13699 &quot;rank&quot;: 3,
13700 &quot;orderno&quot;: 1003
13701 },
13702 {
13703 &quot;items&quot;: 2,
13704 &quot;rank&quot;: 3,
13705 &quot;orderno&quot;: 1004
13706 },
13707 {
13708 &quot;items&quot;: 2,
13709 &quot;rank&quot;: 3,
13710 &quot;orderno&quot;: 1007
13711 },
13712 {
13713 &quot;items&quot;: 3,
13714 &quot;rank&quot;: 4,
13715 &quot;orderno&quot;: 1006
13716 },
13717 {
13718 &quot;items&quot;: 4,
13719 &quot;rank&quot;: 5,
13720 &quot;orderno&quot;: 1005
13721 }
13722]
13723</pre></div></div>
13724</li>
13725</ul></div>
13726<div class="section">
13727<h3><a name="first_value"></a>first_value</h3>
13728<ul>
13729
13730<li>
13731
13732<p>Syntax:</p>
13733
13734<div>
13735<div>
13736<pre class="source">FIRST_VALUE(expr) [nulls-modifier] OVER (window-definition)
13737</pre></div></div>
13738</li>
13739<li>
13740
13741<p>Returns the requested value from the first tuple in the current window frame, where the window frame is specified by the window definition.</p>
13742</li>
13743<li>
13744
13745<p>Arguments:</p>
13746<ul>
13747
13748<li><tt>expr</tt>: The value that you want to return from the first tuple in the window frame. <sup>[</sup><a href="#fn_1"><sup>1</sup></a><sup>]</sup></li>
13749</ul>
13750</li>
13751<li>
13752
13753<p>Modifiers:</p>
13754<ul>
13755
13756<li><a href="manual.html#Window_function_options">NULLS Modifier</a>: (Optional) Determines how NULL or MISSING values are treated when finding the first value in the window frame.
13757<ul>
13758
13759<li>
13760
13761<p><tt>IGNORE NULLS</tt>: If the values for any tuples evaluate to NULL or MISSING, those tuples are ignored when finding the first tuple. In this case, the function returns the first non-NULL, non-MISSING value.</p>
13762</li>
13763<li>
13764
13765<p><tt>RESPECT NULLS</tt>: If the values for any tuples evaluate to NULL or MISSING, those tuples are included when finding the first tuple.</p>
13766</li>
13767</ul>
13768<p>If this modifier is omitted, the default is <tt>RESPECT NULLS</tt>.</p>
13769</li>
13770</ul>
13771</li>
13772<li>
13773
13774<p>Clauses:</p>
13775<ul>
13776
13777<li>
13778
13779<p>(Optional) <a href="manual.html#Window_partition_clause">Window Partition Clause</a>.</p>
13780</li>
13781<li>
13782
13783<p>(Optional) <a href="manual.html#Window_order_clause">Window Order Clause</a>.</p>
13784</li>
13785<li>
13786
13787<p>(Optional) <a href="manual.html#Window_frame_clause">Window Frame Clause</a>.</p>
13788</li>
13789</ul>
13790</li>
13791<li>
13792
13793<p>Return Value:</p>
13794<ul>
13795
13796<li>
13797
13798<p>The specified value from the first tuple. The order of the tuples is determined by the window order clause.</p>
13799</li>
13800<li>
13801
13802<p>NULL, if the frame was empty or if all values were NULL or MISSING and the <tt>IGNORE NULLS</tt> modifier was specified.</p>
13803</li>
13804<li>
13805
13806<p>In the following cases, this function may return unpredictable results.</p>
13807<ul>
13808
13809<li>
13810
13811<p>If the window order clause is omitted.</p>
13812</li>
13813<li>
13814
13815<p>If the window frame is defined by <tt>ROWS</tt>, and there are tied tuples in the window frame.</p>
13816</li>
13817</ul>
13818</li>
13819<li>
13820
13821<p>To make the function return deterministic results, add a window order clause, or add further ordering terms to the window order clause so that no tuples are tied.</p>
13822</li>
13823<li>
13824
13825<p>If the window frame is defined by <tt>RANGE</tt> or <tt>GROUPS</tt>, and there are tied tuples in the window frame, the function returns the first value of the input expression.</p>
13826</li>
13827</ul>
13828</li>
13829<li>
13830
13831<p>Example:</p>
13832<p>For each order, show the customer and the value, including the value of the smallest order from that customer.</p>
13833
13834<div>
13835<div>
13836<pre class="source">FROM orders AS o
13837LET revenue = ROUND((
13838 FROM o.items
13839 SELECT VALUE SUM(qty * price)
13840)[0], 2)
13841SELECT o.custid, o.orderno, revenue,
13842FIRST_VALUE(revenue) OVER (
13843 PARTITION BY o.custid
13844 ORDER BY revenue
13845) AS smallest_order;
13846</pre></div></div>
13847</li>
13848<li>
13849
13850<p>The expected result is:</p>
13851
13852<div>
13853<div>
13854<pre class="source">[
13855 {
13856 &quot;custid&quot;: &quot;C13&quot;,
13857 &quot;orderno&quot;: 1009,
13858 &quot;revenue&quot;: null,
13859 &quot;smallest_order&quot;: null
13860 },
13861 {
13862 &quot;custid&quot;: &quot;C13&quot;,
13863 &quot;orderno&quot;: 1007,
13864 &quot;revenue&quot;: 130.45,
13865 &quot;smallest_order&quot;: null
13866 },
13867 {
13868 &quot;custid&quot;: &quot;C13&quot;,
13869 &quot;orderno&quot;: 1008,
13870 &quot;revenue&quot;: 1999.8,
13871 &quot;smallest_order&quot;: null
13872 },
13873 {
13874 &quot;custid&quot;: &quot;C13&quot;,
13875 &quot;orderno&quot;: 1002,
13876 &quot;revenue&quot;: 10906.55,
13877 &quot;smallest_order&quot;: null
13878 },
13879 {
13880 &quot;custid&quot;: &quot;C31&quot;,
13881 &quot;orderno&quot;: 1003,
13882 &quot;revenue&quot;: 477.95,
13883 &quot;smallest_order&quot;: 477.95
13884 },
13885 {
13886 &quot;custid&quot;: &quot;C35&quot;,
13887 &quot;orderno&quot;: 1004,
13888 &quot;revenue&quot;: 199.94,
13889 &quot;smallest_order&quot;: 199.94
13890 },
13891 {
13892 &quot;custid&quot;: &quot;C37&quot;,
13893 &quot;orderno&quot;: 1005,
13894 &quot;revenue&quot;: 4639.92,
13895 &quot;smallest_order&quot;: 4639.92
13896 },
13897 {
13898 &quot;custid&quot;: &quot;C41&quot;,
13899 &quot;orderno&quot;: 1001,
13900 &quot;revenue&quot;: 157.73,
13901 &quot;smallest_order&quot;: 157.73
13902 },
13903 {
13904 &quot;custid&quot;: &quot;C41&quot;,
13905 &quot;orderno&quot;: 1006,
13906 &quot;revenue&quot;: 18847.58,
13907 &quot;smallest_order&quot;: 157.73
13908 }
13909]
13910</pre></div></div>
13911</li>
13912</ul></div>
13913<div class="section">
13914<h3><a name="lag"></a>lag</h3>
13915<ul>
13916
13917<li>
13918
13919<p>Syntax:</p>
13920
13921<div>
13922<div>
13923<pre class="source">LAG(expr[, offset[, default]]) [nulls-modifier] OVER ([window-partition-clause] [window-order-clause])
13924</pre></div></div>
13925</li>
13926<li>
13927
13928<p>Returns the value from a tuple at a given offset prior to the current tuple position.</p>
13929<p>The window order clause determines the sort order of the tuples. If the window order clause is omitted, the return values may be unpredictable.</p>
13930</li>
13931<li>
13932
13933<p>Arguments:</p>
13934<ul>
13935
13936<li>
13937
13938<p><tt>expr</tt>: The value that you want to return from the offset tuple. <sup>[</sup><a href="#fn_1"><sup>1</sup></a><sup>]</sup></p>
13939</li>
13940<li>
13941
13942<p><tt>offset</tt>: (Optional) A positive integer. If omitted, the default is 1.</p>
13943</li>
13944<li>
13945
13946<p><tt>default</tt>: (Optional) The value to return when the offset goes out of partition scope. If omitted, the default is NULL.</p>
13947</li>
13948</ul>
13949</li>
13950<li>
13951
13952<p>Modifiers:</p>
13953<ul>
13954
13955<li><a href="manual.html#Window_function_options">NULLS Modifier</a>: (Optional) Determines how NULL or MISSING values are treated when finding the offset tuple in the window partition.
13956<ul>
13957
13958<li>
13959
13960<p><tt>IGNORE NULLS</tt>: If the values for any tuples evaluate to NULL or MISSING, those tuples are ignored when finding the offset tuple.</p>
13961</li>
13962<li>
13963
13964<p><tt>RESPECT NULLS</tt>: If the values for any tuples evaluate to NULL or MISSING, those tuples are included when finding the offset tuple.</p>
13965</li>
13966</ul>
13967<p>If this modifier is omitted, the default is <tt>RESPECT NULLS</tt>.</p>
13968</li>
13969</ul>
13970</li>
13971<li>
13972
13973<p>Clauses:</p>
13974<ul>
13975
13976<li>
13977
13978<p>(Optional) <a href="manual.html#Window_partition_clause">Window Partition Clause</a>.</p>
13979</li>
13980<li>
13981
13982<p>(Optional) <a href="manual.html#Window_order_clause">Window Order Clause</a>.</p>
13983</li>
13984</ul>
13985</li>
13986<li>
13987
13988<p>Return Value:</p>
13989<ul>
13990
13991<li>
13992
13993<p>The specified value from the offset tuple.</p>
13994</li>
13995<li>
13996
13997<p>If the offset tuple is out of partition scope, it returns the default value, or NULL if no default is specified.</p>
13998</li>
13999</ul>
14000</li>
14001<li>
14002
14003<p>Example:</p>
14004<p>For each order, show the customer and the value, including the value of the next-smallest order from that customer.</p>
14005
14006<div>
14007<div>
14008<pre class="source">FROM orders AS o
14009LET revenue = ROUND((
14010 FROM o.items
14011 SELECT VALUE SUM(qty * price)
14012)[0], 2)
14013SELECT o.custid, o.orderno, revenue,
14014LAG(revenue, 1, &quot;No smaller order&quot;) OVER (
14015 PARTITION BY o.custid
14016 ORDER BY revenue
14017) AS next_smallest_order;
14018</pre></div></div>
14019</li>
14020<li>
14021
14022<p>The expected result is:</p>
14023
14024<div>
14025<div>
14026<pre class="source">[
14027 {
14028 &quot;custid&quot;: &quot;C13&quot;,
14029 &quot;orderno&quot;: 1009,
14030 &quot;revenue&quot;: null,
14031 &quot;next_smallest_order&quot;: &quot;No smaller order&quot;
14032 },
14033 {
14034 &quot;custid&quot;: &quot;C13&quot;,
14035 &quot;orderno&quot;: 1007,
14036 &quot;revenue&quot;: 130.45,
14037 &quot;next_smallest_order&quot;: null
14038 },
14039 {
14040 &quot;custid&quot;: &quot;C13&quot;,
14041 &quot;orderno&quot;: 1008,
14042 &quot;revenue&quot;: 1999.8,
14043 &quot;next_smallest_order&quot;: 130.45
14044 },
14045 {
14046 &quot;custid&quot;: &quot;C13&quot;,
14047 &quot;orderno&quot;: 1002,
14048 &quot;revenue&quot;: 10906.55,
14049 &quot;next_smallest_order&quot;: 1999.8
14050 },
14051 {
14052 &quot;custid&quot;: &quot;C31&quot;,
14053 &quot;orderno&quot;: 1003,
14054 &quot;revenue&quot;: 477.95,
14055 &quot;next_smallest_order&quot;: &quot;No smaller order&quot;
14056 },
14057 {
14058 &quot;custid&quot;: &quot;C35&quot;,
14059 &quot;orderno&quot;: 1004,
14060 &quot;revenue&quot;: 199.94,
14061 &quot;next_smallest_order&quot;: &quot;No smaller order&quot;
14062 },
14063 {
14064 &quot;custid&quot;: &quot;C37&quot;,
14065 &quot;orderno&quot;: 1005,
14066 &quot;revenue&quot;: 4639.92,
14067 &quot;next_smallest_order&quot;: &quot;No smaller order&quot;
14068 },
14069 {
14070 &quot;custid&quot;: &quot;C41&quot;,
14071 &quot;orderno&quot;: 1001,
14072 &quot;revenue&quot;: 157.73,
14073 &quot;next_smallest_order&quot;: &quot;No smaller order&quot;
14074 },
14075 {
14076 &quot;custid&quot;: &quot;C41&quot;,
14077 &quot;orderno&quot;: 1006,
14078 &quot;revenue&quot;: 18847.58,
14079 &quot;next_smallest_order&quot;: 157.73
14080 }
14081]
14082</pre></div></div>
14083</li>
14084</ul></div>
14085<div class="section">
14086<h3><a name="last_value"></a>last_value</h3>
14087<ul>
14088
14089<li>
14090
14091<p>Syntax:</p>
14092
14093<div>
14094<div>
14095<pre class="source">LAST_VALUE(expr) [nulls-modifier] OVER (window-definition)
14096</pre></div></div>
14097</li>
14098<li>
14099
14100<p>Returns the requested value from the last tuple in the current window frame, where the window frame is specified by the window definition.</p>
14101</li>
14102<li>
14103
14104<p>Arguments:</p>
14105<ul>
14106
14107<li><tt>expr</tt>: The value that you want to return from the last tuple in the window frame. <sup>[</sup><a href="#fn_1"><sup>1</sup></a><sup>]</sup></li>
14108</ul>
14109</li>
14110<li>
14111
14112<p>Modifiers:</p>
14113<ul>
14114
14115<li><a href="manual.html#Window_function_options">NULLS Modifier</a>: (Optional) Determines how NULL or MISSING values are treated when finding the last tuple in the window frame.
14116<ul>
14117
14118<li>
14119
14120<p><tt>IGNORE NULLS</tt>: If the values for any tuples evaluate to NULL or MISSING, those tuples are ignored when finding the last tuple. In this case, the function returns the last non-NULL, non-MISSING value.</p>
14121</li>
14122<li>
14123
14124<p><tt>RESPECT NULLS</tt>: If the values for any tuples evaluate to NULL or MISSING, those tuples are included when finding the last tuple.</p>
14125</li>
14126</ul>
14127<p>If this modifier is omitted, the default is <tt>RESPECT NULLS</tt>.</p>
14128</li>
14129</ul>
14130</li>
14131<li>
14132
14133<p>Clauses:</p>
14134<ul>
14135
14136<li>
14137
14138<p>(Optional) <a href="manual.html#Window_partition_clause">Window Partition Clause</a>.</p>
14139</li>
14140<li>
14141
14142<p>(Optional) <a href="manual.html#Window_order_clause">Window Order Clause</a>.</p>
14143</li>
14144<li>
14145
14146<p>(Optional) <a href="manual.html#Window_frame_clause">Window Frame Clause</a>.</p>
14147</li>
14148</ul>
14149</li>
14150<li>
14151
14152<p>Return Value:</p>
14153<ul>
14154
14155<li>
14156
14157<p>The specified value from the last tuple. The order of the tuples is determined by the window order clause.</p>
14158</li>
14159<li>
14160
14161<p>NULL, if the frame was empty or if all values were NULL or MISSING and the <tt>IGNORE NULLS</tt> modifier was specified.</p>
14162</li>
14163<li>
14164
14165<p>In the following cases, this function may return unpredictable results.</p>
14166<ul>
14167
14168<li>
14169
14170<p>If the window order clause is omitted.</p>
14171</li>
14172<li>
14173
14174<p>If the window frame clause is omitted.</p>
14175</li>
14176<li>
14177
14178<p>If the window frame is defined by <tt>ROWS</tt>, and there are tied tuples in the window frame.</p>
14179</li>
14180</ul>
14181</li>
14182<li>
14183
14184<p>To make the function return deterministic results, add a window order clause, or add further ordering terms to the window order clause so that no tuples are tied.</p>
14185</li>
14186<li>
14187
14188<p>If the window frame is defined by <tt>RANGE</tt> or <tt>GROUPS</tt>, and there are tied tuples in the window frame, the function returns the last value of the input expression.</p>
14189</li>
14190</ul>
14191</li>
14192<li>
14193
14194<p>Example:</p>
14195<p>For each order, show the customer and the value, including the value of the largest order from that customer.</p>
14196
14197<div>
14198<div>
14199<pre class="source">FROM orders AS o
14200LET revenue = ROUND((
14201 FROM o.items
14202 SELECT VALUE SUM(qty * price)
14203)[0], 2)
14204SELECT o.custid, o.orderno, revenue,
14205LAST_VALUE(revenue) OVER (
14206 PARTITION BY o.custid
14207 ORDER BY revenue
14208 ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING -- &#x278a;
14209) AS largest_order;
14210</pre></div></div>
14211</li>
14212<li>
14213
14214<p>The expected result is:</p>
14215
14216<div>
14217<div>
14218<pre class="source">[
14219 {
14220 &quot;custid&quot;: &quot;C13&quot;,
14221 &quot;orderno&quot;: 1009,
14222 &quot;revenue&quot;: null,
14223 &quot;largest_order&quot;: 10906.55
14224 },
14225 {
14226 &quot;custid&quot;: &quot;C13&quot;,
14227 &quot;orderno&quot;: 1007,
14228 &quot;revenue&quot;: 130.45,
14229 &quot;largest_order&quot;: 10906.55
14230 },
14231 {
14232 &quot;custid&quot;: &quot;C13&quot;,
14233 &quot;orderno&quot;: 1008,
14234 &quot;revenue&quot;: 1999.8,
14235 &quot;largest_order&quot;: 10906.55
14236 },
14237 {
14238 &quot;custid&quot;: &quot;C13&quot;,
14239 &quot;orderno&quot;: 1002,
14240 &quot;revenue&quot;: 10906.55,
14241 &quot;largest_order&quot;: 10906.55
14242 },
14243 {
14244 &quot;custid&quot;: &quot;C31&quot;,
14245 &quot;orderno&quot;: 1003,
14246 &quot;revenue&quot;: 477.95,
14247 &quot;largest_order&quot;: 477.95
14248 },
14249 {
14250 &quot;custid&quot;: &quot;C35&quot;,
14251 &quot;orderno&quot;: 1004,
14252 &quot;revenue&quot;: 199.94,
14253 &quot;largest_order&quot;: 199.94
14254 },
14255 {
14256 &quot;custid&quot;: &quot;C37&quot;,
14257 &quot;orderno&quot;: 1005,
14258 &quot;revenue&quot;: 4639.92,
14259 &quot;largest_order&quot;: 4639.92
14260 },
14261 {
14262 &quot;custid&quot;: &quot;C41&quot;,
14263 &quot;orderno&quot;: 1001,
14264 &quot;revenue&quot;: 157.73,
14265 &quot;largest_order&quot;: 18847.58
14266 },
14267 {
14268 &quot;custid&quot;: &quot;C41&quot;,
14269 &quot;orderno&quot;: 1006,
14270 &quot;revenue&quot;: 18847.58,
14271 &quot;largest_order&quot;: 18847.58
14272 }
14273]
14274</pre></div></div>
14275
14276<p>&#x2780; This clause specifies that the window frame should extend to the end of the window partition. Without this clause, the end point of the window frame would always be the current tuple. This would mean that the largest order would always be the same as the current order.</p>
14277</li>
14278</ul></div>
14279<div class="section">
14280<h3><a name="lead"></a>lead</h3>
14281<ul>
14282
14283<li>
14284
14285<p>Syntax:</p>
14286
14287<div>
14288<div>
14289<pre class="source">LEAD(expr[, offset[, default]]) [nulls-modifier] OVER ([window-partition-clause] [window-order-clause])
14290</pre></div></div>
14291</li>
14292<li>
14293
14294<p>Returns the value from a tuple at a given offset ahead of the current tuple position.</p>
14295<p>The window order clause determines the sort order of the tuples. If the window order clause is omitted, the return values may be unpredictable.</p>
14296</li>
14297<li>
14298
14299<p>Arguments:</p>
14300<ul>
14301
14302<li>
14303
14304<p><tt>expr</tt>: The value that you want to return from the offset tuple. <sup>[</sup><a href="#fn_1"><sup>1</sup></a><sup>]</sup></p>
14305</li>
14306<li>
14307
14308<p><tt>offset</tt>: (Optional) A positive integer. If omitted, the default is 1.</p>
14309</li>
14310<li>
14311
14312<p><tt>default</tt>: (Optional) The value to return when the offset goes out of window partition scope. If omitted, the default is NULL.</p>
14313</li>
14314</ul>
14315</li>
14316<li>
14317
14318<p>Modifiers:</p>
14319<ul>
14320
14321<li><a href="manual.html#Window_function_options">NULLS Modifier</a>: (Optional) Determines how NULL or MISSING values are treated when finding the offset tuple in the window partition.
14322<ul>
14323
14324<li>
14325
14326<p><tt>IGNORE NULLS</tt>: If the values for any tuples evaluate to NULL or MISSING, those tuples are ignored when finding the offset tuple.</p>
14327</li>
14328<li>
14329
14330<p><tt>RESPECT NULLS</tt>: If the values for any tuples evaluate to NULL or MISSING, those tuples are included when finding the offset tuple.</p>
14331</li>
14332</ul>
14333<p>If this modifier is omitted, the default is <tt>RESPECT NULLS</tt>.</p>
14334</li>
14335</ul>
14336</li>
14337<li>
14338
14339<p>Clauses:</p>
14340<ul>
14341
14342<li>
14343
14344<p>(Optional) <a href="manual.html#Window_partition_clause">Window Partition Clause</a>.</p>
14345</li>
14346<li>
14347
14348<p>(Optional) <a href="manual.html#Window_order_clause">Window Order Clause</a>.</p>
14349</li>
14350</ul>
14351</li>
14352<li>
14353
14354<p>Return Value:</p>
14355<ul>
14356
14357<li>
14358
14359<p>The specified value from the offset tuple.</p>
14360</li>
14361<li>
14362
14363<p>If the offset tuple is out of partition scope, it returns the default value, or NULL if no default is specified.</p>
14364</li>
14365</ul>
14366</li>
14367<li>
14368
14369<p>Example:</p>
14370<p>For each order, show the customer and the value, including the value of the next-largest order from that customer.</p>
14371
14372<div>
14373<div>
14374<pre class="source">FROM orders AS o
14375LET revenue = ROUND((
14376 FROM o.items
14377 SELECT VALUE SUM(qty * price)
14378)[0], 2)
14379SELECT o.custid, o.orderno, revenue,
14380LEAD(revenue, 1, &quot;No larger order&quot;) OVER (
14381 PARTITION BY o.custid
14382 ORDER BY revenue
14383) AS next_largest_order;
14384</pre></div></div>
14385</li>
14386<li>
14387
14388<p>The expected result is:</p>
14389
14390<div>
14391<div>
14392<pre class="source">[
14393 {
14394 &quot;custid&quot;: &quot;C13&quot;,
14395 &quot;orderno&quot;: 1009,
14396 &quot;revenue&quot;: null,
14397 &quot;next_largest_order&quot;: 130.45
14398 },
14399 {
14400 &quot;custid&quot;: &quot;C13&quot;,
14401 &quot;orderno&quot;: 1007,
14402 &quot;revenue&quot;: 130.45,
14403 &quot;next_largest_order&quot;: 1999.8
14404 },
14405 {
14406 &quot;custid&quot;: &quot;C13&quot;,
14407 &quot;orderno&quot;: 1008,
14408 &quot;revenue&quot;: 1999.8,
14409 &quot;next_largest_order&quot;: 10906.55
14410 },
14411 {
14412 &quot;custid&quot;: &quot;C13&quot;,
14413 &quot;orderno&quot;: 1002,
14414 &quot;revenue&quot;: 10906.55,
14415 &quot;next_largest_order&quot;: &quot;No larger order&quot;
14416 },
14417 {
14418 &quot;custid&quot;: &quot;C31&quot;,
14419 &quot;orderno&quot;: 1003,
14420 &quot;revenue&quot;: 477.95,
14421 &quot;next_largest_order&quot;: &quot;No larger order&quot;
14422 },
14423 {
14424 &quot;custid&quot;: &quot;C35&quot;,
14425 &quot;orderno&quot;: 1004,
14426 &quot;revenue&quot;: 199.94,
14427 &quot;next_largest_order&quot;: &quot;No larger order&quot;
14428 },
14429 {
14430 &quot;custid&quot;: &quot;C37&quot;,
14431 &quot;orderno&quot;: 1005,
14432 &quot;revenue&quot;: 4639.92,
14433 &quot;next_largest_order&quot;: &quot;No larger order&quot;
14434 },
14435 {
14436 &quot;custid&quot;: &quot;C41&quot;,
14437 &quot;orderno&quot;: 1001,
14438 &quot;revenue&quot;: 157.73,
14439 &quot;next_largest_order&quot;: 18847.58
14440 },
14441 {
14442 &quot;custid&quot;: &quot;C41&quot;,
14443 &quot;orderno&quot;: 1006,
14444 &quot;revenue&quot;: 18847.58,
14445 &quot;next_largest_order&quot;: &quot;No larger order&quot;
14446 }
14447]
14448</pre></div></div>
14449</li>
14450</ul></div>
14451<div class="section">
14452<h3><a name="nth_value"></a>nth_value</h3>
14453<ul>
14454
14455<li>
14456
14457<p>Syntax:</p>
14458
14459<div>
14460<div>
14461<pre class="source">NTH_VALUE(expr, offset) [from-modifier] [nulls-modifier] OVER (window-definition)
14462</pre></div></div>
14463</li>
14464<li>
14465
14466<p>Returns the requested value from a tuple in the current window frame, where the window frame is specified by the window definition.</p>
14467</li>
14468<li>
14469
14470<p>Arguments:</p>
14471<ul>
14472
14473<li>
14474
14475<p><tt>expr</tt>: The value that you want to return from the offset tuple in the window frame. <sup>[</sup><a href="#fn_1"><sup>1</sup></a><sup>]</sup></p>
14476</li>
14477<li>
14478
14479<p><tt>offset</tt>: The number of the offset tuple within the window frame, counting from 1.</p>
14480</li>
14481</ul>
14482</li>
14483<li>
14484
14485<p>Modifiers:</p>
14486<ul>
14487
14488<li>
14489
14490<p><a href="manual.html#Window_function_options">FROM Modifier</a>: (Optional) Determines where the function starts counting the offset.</p>
14491<ul>
14492
14493<li>
14494
14495<p><tt>FROM FIRST</tt>: Counting starts at the first tuple in the window frame. In this case, an offset of 1 is the first tuple in the window frame, 2 is the second tuple, and so on.</p>
14496</li>
14497<li>
14498
14499<p><tt>FROM LAST</tt>: Counting starts at the last tuple in the window frame. In this case, an offset of 1 is the last tuple in the window frame, 2 is the second-to-last tuple, and so on.</p>
14500</li>
14501</ul>
14502<p>The order of the tuples is determined by the window order clause. If this modifier is omitted, the default is <tt>FROM FIRST</tt>.</p>
14503</li>
14504<li>
14505
14506<p><a href="manual.html#Window_function_options">NULLS Modifier</a>: (Optional) Determines how NULL or MISSING values are treated when finding the offset tuple in the window frame.</p>
14507<ul>
14508
14509<li>
14510
14511<p><tt>IGNORE NULLS</tt>: If the values for any tuples evaluate to NULL or MISSING, those tuples are ignored when finding the offset tuple.</p>
14512</li>
14513<li>
14514
14515<p><tt>RESPECT NULLS</tt>: If the values for any tuples evaluate to NULL or MISSING, those tuples are included when finding the offset tuple.</p>
14516</li>
14517</ul>
14518<p>If this modifier is omitted, the default is <tt>RESPECT NULLS</tt>.</p>
14519</li>
14520</ul>
14521</li>
14522<li>
14523
14524<p>Clauses:</p>
14525<ul>
14526
14527<li>
14528
14529<p>(Optional) <a href="manual.html#Window_partition_clause">Window Partition Clause</a>.</p>
14530</li>
14531<li>
14532
14533<p>(Optional) <a href="manual.html#Window_order_clause">Window Order Clause</a>.</p>
14534</li>
14535<li>
14536
14537<p>(Optional) <a href="manual.html#Window_frame_clause">Window Frame Clause</a>.</p>
14538</li>
14539</ul>
14540</li>
14541<li>
14542
14543<p>Return Value:</p>
14544<ul>
14545
14546<li>
14547
14548<p>The specified value from the offset tuple.</p>
14549</li>
14550<li>
14551
14552<p>In the following cases, this function may return unpredictable results.</p>
14553<ul>
14554
14555<li>
14556
14557<p>If the window order clause is omitted.</p>
14558</li>
14559<li>
14560
14561<p>If the window frame is defined by <tt>ROWS</tt>, and there are tied tuples in the window frame.</p>
14562</li>
14563</ul>
14564</li>
14565<li>
14566
14567<p>To make the function return deterministic results, add a window order clause, or add further ordering terms to the window order clause so that no tuples are tied.</p>
14568</li>
14569<li>
14570
14571<p>If the window frame is defined by <tt>RANGE</tt> or <tt>GROUPS</tt>, and there are tied tuples in the window frame, the function returns the first value of the input expression when counting <tt>FROM FIRST</tt>, or the last value of the input expression when counting <tt>FROM LAST</tt>.</p>
14572</li>
14573</ul>
14574</li>
14575<li>
14576
14577<p>Example 1:</p>
14578<p>For each order, show the customer and the value, including the value of the second smallest order from that customer.</p>
14579
14580<div>
14581<div>
14582<pre class="source">FROM orders AS o
14583LET revenue = ROUND((
14584 FROM o.items
14585 SELECT VALUE SUM(qty * price)
14586)[0], 2)
14587SELECT o.custid, o.orderno, revenue,
14588NTH_VALUE(revenue, 2) FROM FIRST OVER (
14589 PARTITION BY o.custid
14590 ORDER BY revenue
14591 ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING -- &#x278a;
14592) AS smallest_order_but_1;
14593</pre></div></div>
14594</li>
14595<li>
14596
14597<p>The expected result is:</p>
14598
14599<div>
14600<div>
14601<pre class="source">[
14602 {
14603 &quot;custid&quot;: &quot;C13&quot;,
14604 &quot;orderno&quot;: 1009,
14605 &quot;revenue&quot;: null,
14606 &quot;smallest_order_but_1&quot;: 130.45
14607 },
14608 {
14609 &quot;custid&quot;: &quot;C13&quot;,
14610 &quot;orderno&quot;: 1007,
14611 &quot;revenue&quot;: 130.45, // &#x278b;
14612 &quot;smallest_order_but_1&quot;: 130.45
14613 },
14614 {
14615 &quot;custid&quot;: &quot;C13&quot;,
14616 &quot;orderno&quot;: 1008,
14617 &quot;revenue&quot;: 1999.8,
14618 &quot;smallest_order_but_1&quot;: 130.45
14619 },
14620 {
14621 &quot;custid&quot;: &quot;C13&quot;,
14622 &quot;orderno&quot;: 1002,
14623 &quot;revenue&quot;: 10906.55,
14624 &quot;smallest_order_but_1&quot;: 130.45
14625 },
14626 {
14627 &quot;custid&quot;: &quot;C31&quot;,
14628 &quot;orderno&quot;: 1003,
14629 &quot;revenue&quot;: 477.95,
14630 &quot;smallest_order_but_1&quot;: null
14631 },
14632 {
14633 &quot;custid&quot;: &quot;C35&quot;,
14634 &quot;orderno&quot;: 1004,
14635 &quot;revenue&quot;: 199.94,
14636 &quot;smallest_order_but_1&quot;: null
14637 },
14638 {
14639 &quot;custid&quot;: &quot;C37&quot;,
14640 &quot;orderno&quot;: 1005,
14641 &quot;revenue&quot;: 4639.92,
14642 &quot;smallest_order_but_1&quot;: null
14643 },
14644 {
14645 &quot;custid&quot;: &quot;C41&quot;,
14646 &quot;orderno&quot;: 1001,
14647 &quot;revenue&quot;: 157.73,
14648 &quot;smallest_order_but_1&quot;: 18847.58
14649 },
14650 {
14651 &quot;custid&quot;: &quot;C41&quot;,
14652 &quot;orderno&quot;: 1006,
14653 &quot;revenue&quot;: 18847.58, // &#x278b;
14654 &quot;smallest_order_but_1&quot;: 18847.58
14655 }
14656]
14657</pre></div></div>
14658
14659<p>&#x2780; This clause specifies that the window frame should extend to the end of the window partition. Without this clause, the end point of the window frame would always be the current tuple. This would mean that for the smallest order, the function would be unable to find the route with the second smallest order.</p>
14660<p>&#x2781; The second smallest order from this customer.</p>
14661</li>
14662<li>
14663
14664<p>Example 2:</p>
14665<p>For each order, show the customer and the value, including the value of the second largest order from that customer.</p>
14666
14667<div>
14668<div>
14669<pre class="source">FROM orders AS o
14670LET revenue = ROUND((
14671 FROM o.items
14672 SELECT VALUE SUM(qty * price)
14673)[0], 2)
14674SELECT o.custid, o.orderno, revenue,
14675NTH_VALUE(revenue, 2) FROM LAST OVER (
14676 PARTITION BY o.custid
14677 ORDER BY revenue
14678 ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING -- &#x278a;
14679) AS largest_order_but_1;
14680</pre></div></div>
14681</li>
14682<li>
14683
14684<p>The expected result is:</p>
14685
14686<div>
14687<div>
14688<pre class="source">[
14689 {
14690 &quot;custid&quot;: &quot;C13&quot;,
14691 &quot;orderno&quot;: 1002,
14692 &quot;revenue&quot;: 10906.55,
14693 &quot;largest_order_but_1&quot;: 1999.8
14694 },
14695 {
14696 &quot;custid&quot;: &quot;C13&quot;,
14697 &quot;orderno&quot;: 1008,
14698 &quot;revenue&quot;: 1999.8, // &#x278b;
14699 &quot;largest_order_but_1&quot;: 1999.8
14700 },
14701 {
14702 &quot;custid&quot;: &quot;C13&quot;,
14703 &quot;orderno&quot;: 1007,
14704 &quot;revenue&quot;: 130.45,
14705 &quot;largest_order_but_1&quot;: 1999.8
14706 },
14707 {
14708 &quot;custid&quot;: &quot;C13&quot;,
14709 &quot;orderno&quot;: 1009,
14710 &quot;revenue&quot;: null,
14711 &quot;largest_order_but_1&quot;: 1999.8
14712 },
14713 {
14714 &quot;custid&quot;: &quot;C31&quot;,
14715 &quot;orderno&quot;: 1003,
14716 &quot;revenue&quot;: 477.95,
14717 &quot;largest_order_but_1&quot;: null
14718 },
14719 {
14720 &quot;custid&quot;: &quot;C35&quot;,
14721 &quot;orderno&quot;: 1004,
14722 &quot;revenue&quot;: 199.94,
14723 &quot;largest_order_but_1&quot;: null
14724 },
14725 {
14726 &quot;custid&quot;: &quot;C37&quot;,
14727 &quot;orderno&quot;: 1005,
14728 &quot;revenue&quot;: 4639.92,
14729 &quot;largest_order_but_1&quot;: null
14730 },
14731 {
14732 &quot;custid&quot;: &quot;C41&quot;,
14733 &quot;orderno&quot;: 1006,
14734 &quot;revenue&quot;: 18847.58,
14735 &quot;largest_order_but_1&quot;: 157.73
14736 },
14737 {
14738 &quot;custid&quot;: &quot;C41&quot;,
14739 &quot;orderno&quot;: 1001,
14740 &quot;revenue&quot;: 157.73, // &#x278b;
14741 &quot;largest_order_but_1&quot;: 157.73
14742 }
14743]
14744</pre></div></div>
14745
14746<p>&#x2780; This clause specifies that the window frame should extend to the end of the window partition. Without this clause, the end point of the window frame would always be the current tuple. This would mean the function would be unable to find the second largest order for smaller orders.</p>
14747<p>&#x2781; The second largest order from this customer.</p>
14748</li>
14749</ul></div>
14750<div class="section">
14751<h3><a name="ntile"></a>ntile</h3>
14752<ul>
14753
14754<li>
14755
14756<p>Syntax:</p>
14757
14758<div>
14759<div>
14760<pre class="source">NTILE(num_tiles) OVER ([window-partition-clause] [window-order-clause])
14761</pre></div></div>
14762</li>
14763<li>
14764
14765<p>Divides the window partition into the specified number of tiles, and allocates each tuple in the window partition to a tile, so that as far as possible each tile has an equal number of tuples. When the set of tuples is not equally divisible by the number of tiles, the function puts more tuples into the lower-numbered tiles. For each tuple, the function returns the number of the tile into which that tuple was placed.</p>
14766<p>The window order clause determines the sort order of the tuples. If the window order clause is omitted then the tuples are processed in an undefined order.</p>
14767</li>
14768<li>
14769
14770<p>Arguments:</p>
14771<ul>
14772
14773<li><tt>num_tiles</tt>: The number of tiles into which you want to divide the window partition. This argument can be an expression and must evaluate to a number. If the number is not an integer, it will be truncated.</li>
14774</ul>
14775</li>
14776<li>
14777
14778<p>Clauses:</p>
14779<ul>
14780
14781<li>
14782
14783<p>(Optional) <a href="manual.html#Window_partition_clause">Window Partition Clause</a>.</p>
14784</li>
14785<li>
14786
14787<p>(Optional) <a href="manual.html#Window_order_clause">Window Order Clause</a>.</p>
14788</li>
14789</ul>
14790</li>
14791<li>
14792
14793<p>Return Value:</p>
14794<ul>
14795
14796<li>An value greater than or equal to 1 and less than or equal to the number of tiles.</li>
14797</ul>
14798</li>
14799<li>
14800
14801<p>Example:</p>
14802<p>Allocate each order to one of three tiles by value.</p>
14803
14804<div>
14805<div>
14806<pre class="source">FROM orders AS o
14807LET revenue = ROUND((
14808 FROM o.items
14809 SELECT VALUE SUM(qty * price)
14810)[0], 2)
14811SELECT o.orderno, revenue,
14812NTILE(3) OVER (
14813 ORDER BY revenue
14814) AS `ntile`;
14815</pre></div></div>
14816</li>
14817<li>
14818
14819<p>The expected result is:</p>
14820
14821<div>
14822<div>
14823<pre class="source">[
14824 {
14825 &quot;ntile&quot;: 1,
14826 &quot;orderno&quot;: 1009,
14827 &quot;revenue&quot;: null
14828 },
14829 {
14830 &quot;ntile&quot;: 1,
14831 &quot;orderno&quot;: 1007,
14832 &quot;revenue&quot;: 130.45
14833 },
14834 {
14835 &quot;ntile&quot;: 1,
14836 &quot;orderno&quot;: 1001,
14837 &quot;revenue&quot;: 157.73
14838 },
14839 {
14840 &quot;ntile&quot;: 2,
14841 &quot;orderno&quot;: 1004,
14842 &quot;revenue&quot;: 199.94
14843 },
14844 {
14845 &quot;ntile&quot;: 2,
14846 &quot;orderno&quot;: 1003,
14847 &quot;revenue&quot;: 477.95
14848 },
14849 {
14850 &quot;ntile&quot;: 2,
14851 &quot;orderno&quot;: 1008,
14852 &quot;revenue&quot;: 1999.8
14853 },
14854 {
14855 &quot;ntile&quot;: 3,
14856 &quot;orderno&quot;: 1005,
14857 &quot;revenue&quot;: 4639.92
14858 },
14859 {
14860 &quot;ntile&quot;: 3,
14861 &quot;orderno&quot;: 1002,
14862 &quot;revenue&quot;: 10906.55
14863 },
14864 {
14865 &quot;ntile&quot;: 3,
14866 &quot;orderno&quot;: 1006,
14867 &quot;revenue&quot;: 18847.58
14868 }
14869]
14870</pre></div></div>
14871</li>
14872</ul></div>
14873<div class="section">
14874<h3><a name="percent_rank"></a>percent_rank</h3>
14875<ul>
14876
14877<li>
14878
14879<p>Syntax:</p>
14880
14881<div>
14882<div>
14883<pre class="source">PERCENT_RANK() OVER ([window-partition-clause] [window-order-clause])
14884</pre></div></div>
14885</li>
14886<li>
14887
14888<p>Returns the percentile rank of the current tuple &#x2013; that is, the rank of the tuples minus one, divided by the total number of tuples in the window partition minus one.</p>
14889<p>The window order clause determines the sort order of the tuples. If the window order clause is omitted, the function returns the same result (0) for each tuple.</p>
14890</li>
14891<li>
14892
14893<p>Arguments:</p>
14894<ul>
14895
14896<li>None.</li>
14897</ul>
14898</li>
14899<li>
14900
14901<p>Clauses:</p>
14902<ul>
14903
14904<li>
14905
14906<p>(Optional) <a href="manual.html#Window_partition_clause">Window Partition Clause</a>.</p>
14907</li>
14908<li>
14909
14910<p>(Optional) <a href="manual.html#Window_order_clause">Window Order Clause</a>.</p>
14911</li>
14912</ul>
14913</li>
14914<li>
14915
14916<p>Return Value:</p>
14917<ul>
14918
14919<li>A number between 0 and 1. The higher the value, the higher the ranking.</li>
14920</ul>
14921</li>
14922<li>
14923
14924<p>Example:</p>
14925<p>For each customer, find the percentile rank of all orders by order number.</p>
14926
14927<div>
14928<div>
14929<pre class="source">FROM orders AS o
14930SELECT o.custid, o.orderno, PERCENT_RANK() OVER (
14931 PARTITION BY o.custid
14932 ORDER BY o.orderno
14933) AS `rank`;
14934</pre></div></div>
14935</li>
14936<li>
14937
14938<p>The expected result is:</p>
14939
14940<div>
14941<div>
14942<pre class="source">[
14943 {
14944 &quot;rank&quot;: 0,
14945 &quot;custid&quot;: &quot;C13&quot;,
14946 &quot;orderno&quot;: 1002
14947 },
14948 {
14949 &quot;rank&quot;: 0.3333333333333333,
14950 &quot;custid&quot;: &quot;C13&quot;,
14951 &quot;orderno&quot;: 1007
14952 },
14953 {
14954 &quot;rank&quot;: 0.6666666666666666,
14955 &quot;custid&quot;: &quot;C13&quot;,
14956 &quot;orderno&quot;: 1008
14957 },
14958 {
14959 &quot;rank&quot;: 1,
14960 &quot;custid&quot;: &quot;C13&quot;,
14961 &quot;orderno&quot;: 1009
14962 },
14963 {
14964 &quot;rank&quot;: 0,
14965 &quot;custid&quot;: &quot;C31&quot;,
14966 &quot;orderno&quot;: 1003
14967 },
14968 {
14969 &quot;rank&quot;: 0,
14970 &quot;custid&quot;: &quot;C35&quot;,
14971 &quot;orderno&quot;: 1004
14972 },
14973 {
14974 &quot;rank&quot;: 0,
14975 &quot;custid&quot;: &quot;C37&quot;,
14976 &quot;orderno&quot;: 1005
14977 },
14978 {
14979 &quot;rank&quot;: 0,
14980 &quot;custid&quot;: &quot;C41&quot;,
14981 &quot;orderno&quot;: 1001
14982 },
14983 {
14984 &quot;rank&quot;: 1,
14985 &quot;custid&quot;: &quot;C41&quot;,
14986 &quot;orderno&quot;: 1006
14987 }
14988]
14989</pre></div></div>
14990</li>
14991</ul></div>
14992<div class="section">
14993<h3><a name="rank"></a>rank</h3>
14994<ul>
14995
14996<li>
14997
14998<p>Syntax:</p>
14999
15000<div>
15001<div>
15002<pre class="source">RANK() OVER ([window-partition-clause] [window-order-clause])
15003</pre></div></div>
15004</li>
15005<li>
15006
15007<p>Returns the rank of the current tuple &#x2013; that is, the number of distinct tuples preceding this tuple in the current window partition, plus one.</p>
15008<p>The tuples are ordered by the window order clause. If any tuples are tied, they will have the same rank. If the window order clause is omitted, the function returns the same result (1) for each tuple.</p>
15009<p>When any tuples have the same rank, the rank of the next tuple will include all preceding tuples, so there may be a gap in the sequence of returned values. For example, if there are five tuples ranked 3, the next rank is 8.</p>
15010<p>To avoid gaps in the returned values, use the DENSE_RANK() function instead.</p>
15011</li>
15012<li>
15013
15014<p>Arguments:</p>
15015<ul>
15016
15017<li>None.</li>
15018</ul>
15019</li>
15020<li>
15021
15022<p>Clauses:</p>
15023<ul>
15024
15025<li>
15026
15027<p>(Optional) <a href="manual.html#Window_partition_clause">Window Partition Clause</a>.</p>
15028</li>
15029<li>
15030
15031<p>(Optional) <a href="manual.html#Window_order_clause">Window Order Clause</a>.</p>
15032</li>
15033</ul>
15034</li>
15035<li>
15036
15037<p>Return Value:</p>
15038<ul>
15039
15040<li>An integer, greater than or equal to 1.</li>
15041</ul>
15042</li>
15043<li>
15044
15045<p>Example:</p>
15046<p>Find the rank of all orders by number of items.</p>
15047
15048<div>
15049<div>
15050<pre class="source">FROM orders AS o
15051SELECT o.orderno, LEN(o.items) AS items,
15052RANK() OVER (
15053 ORDER BY LEN(o.items)
15054) AS `rank`;
15055</pre></div></div>
15056</li>
15057<li>
15058
15059<p>The expected result is:</p>
15060
15061<div>
15062<div>
15063<pre class="source">[
15064 {
15065 &quot;items&quot;: 0,
15066 &quot;rank&quot;: 1,
15067 &quot;orderno&quot;: 1009
15068 },
15069 {
15070 &quot;items&quot;: 1,
15071 &quot;rank&quot;: 2,
15072 &quot;orderno&quot;: 1008
15073 },
15074 {
15075 &quot;items&quot;: 2,
15076 &quot;rank&quot;: 3,
15077 &quot;orderno&quot;: 1004
15078 },
15079 {
15080 &quot;items&quot;: 2,
15081 &quot;rank&quot;: 3,
15082 &quot;orderno&quot;: 1007
15083 },
15084 {
15085 &quot;items&quot;: 2,
15086 &quot;rank&quot;: 3,
15087 &quot;orderno&quot;: 1002
15088 },
15089 {
15090 &quot;items&quot;: 2,
15091 &quot;rank&quot;: 3,
15092 &quot;orderno&quot;: 1001
15093 },
15094 {
15095 &quot;items&quot;: 2,
15096 &quot;rank&quot;: 3,
15097 &quot;orderno&quot;: 1003
15098 },
15099 {
15100 &quot;items&quot;: 3,
15101 &quot;rank&quot;: 8,
15102 &quot;orderno&quot;: 1006
15103 },
15104 {
15105 &quot;items&quot;: 4,
15106 &quot;rank&quot;: 9,
15107 &quot;orderno&quot;: 1005
15108 }
15109]
15110</pre></div></div>
15111</li>
15112</ul></div>
15113<div class="section">
15114<h3><a name="ratio_to_report"></a>ratio_to_report</h3>
15115<ul>
15116
15117<li>
15118
15119<p>Syntax:</p>
15120
15121<div>
15122<div>
15123<pre class="source">RATIO_TO_REPORT(expr) OVER (window-definition)
15124</pre></div></div>
15125</li>
15126<li>
15127
15128<p>Returns the fractional ratio of the specified value for each tuple to the sum of values for all tuples in the window frame.</p>
15129</li>
15130<li>
15131
15132<p>Arguments:</p>
15133<ul>
15134
15135<li><tt>expr</tt>: The value for which you want to calculate the fractional ratio. <sup>[</sup><a href="#fn_1"><sup>1</sup></a><sup>]</sup></li>
15136</ul>
15137</li>
15138<li>
15139
15140<p>Clauses:</p>
15141<ul>
15142
15143<li>
15144
15145<p>(Optional) <a href="manual.html#Window_partition_clause">Window Partition Clause</a>.</p>
15146</li>
15147<li>
15148
15149<p>(Optional) <a href="manual.html#Window_order_clause">Window Order Clause</a>.</p>
15150</li>
15151<li>
15152
15153<p>(Optional) <a href="manual.html#Window_frame_clause">Window Frame Clause</a>.</p>
15154</li>
15155</ul>
15156</li>
15157<li>
15158
15159<p>Return Value:</p>
15160<ul>
15161
15162<li>
15163
15164<p>A number between 0 and 1, representing the fractional ratio of the value for the current tuple to the sum of values for all tuples in the current window frame. The sum of returned values for all tuples in the current window frame is 1.</p>
15165</li>
15166<li>
15167
15168<p>If the input expression does not evaluate to a number, or the sum of values for all tuples is zero, it returns NULL.</p>
15169</li>
15170</ul>
15171</li>
15172<li>
15173
15174<p>Example:</p>
15175<p>For each customer, calculate the value of each order as a fraction of the total value of all orders.</p>
15176
15177<div>
15178<div>
15179<pre class="source">FROM orders AS o
15180LET revenue = ROUND((
15181 FROM o.items
15182 SELECT VALUE SUM(qty * price)
15183)[0], 2)
15184SELECT o.custid, o.orderno,
15185RATIO_TO_REPORT(revenue) OVER (
15186 PARTITION BY o.custid
15187) AS fractional_ratio;
15188</pre></div></div>
15189</li>
15190<li>
15191
15192<p>The expected result is:</p>
15193
15194<div>
15195<div>
15196<pre class="source">[
15197 {
15198 &quot;custid&quot;: &quot;C13&quot;,
15199 &quot;orderno&quot;: 1007,
15200 &quot;fractional_ratio&quot;: 0.010006289887088855
15201 },
15202 {
15203 &quot;custid&quot;: &quot;C13&quot;,
15204 &quot;orderno&quot;: 1002,
15205 &quot;fractional_ratio&quot;: 0.8365971710849288
15206 },
15207 {
15208 &quot;custid&quot;: &quot;C13&quot;,
15209 &quot;orderno&quot;: 1009,
15210 &quot;fractional_ratio&quot;: null
15211 },
15212 {
15213 &quot;custid&quot;: &quot;C13&quot;,
15214 &quot;orderno&quot;: 1008,
15215 &quot;fractional_ratio&quot;: 0.15339653902798234
15216 },
15217 {
15218 &quot;custid&quot;: &quot;C31&quot;,
15219 &quot;orderno&quot;: 1003,
15220 &quot;fractional_ratio&quot;: 1
15221 },
15222 {
15223 &quot;custid&quot;: &quot;C35&quot;,
15224 &quot;orderno&quot;: 1004,
15225 &quot;fractional_ratio&quot;: 1
15226 },
15227 {
15228 &quot;custid&quot;: &quot;C37&quot;,
15229 &quot;orderno&quot;: 1005,
15230 &quot;fractional_ratio&quot;: 1
15231 },
15232 {
15233 &quot;custid&quot;: &quot;C41&quot;,
15234 &quot;orderno&quot;: 1006,
15235 &quot;fractional_ratio&quot;: 0.9917007404772666
15236 },
15237 {
15238 &quot;custid&quot;: &quot;C41&quot;,
15239 &quot;orderno&quot;: 1001,
15240 &quot;fractional_ratio&quot;: 0.008299259522733382
15241 }
15242]
15243</pre></div></div>
15244</li>
15245</ul></div>
15246<div class="section">
15247<h3><a name="row_number"></a>row_number</h3>
15248<ul>
15249
15250<li>
15251
15252<p>Syntax:</p>
15253
15254<div>
15255<div>
15256<pre class="source">ROW_NUMBER() OVER ([window-partition-clause] [window-order-clause])
15257</pre></div></div>
15258</li>
15259<li>
15260
15261<p>Returns a unique row number for every tuple in every window partition. In each window partition, the row numbering starts at 1.</p>
15262<p>The window order clause determines the sort order of the tuples. If the window order clause is omitted, the return values may be unpredictable.</p>
15263</li>
15264<li>
15265
15266<p>Arguments:</p>
15267<ul>
15268
15269<li>None.</li>
15270</ul>
15271</li>
15272<li>
15273
15274<p>Clauses:</p>
15275<ul>
15276
15277<li>
15278
15279<p>(Optional) <a href="manual.html#Window_partition_clause">Window Partition Clause</a>.</p>
15280</li>
15281<li>
15282
15283<p>(Optional) <a href="manual.html#Window_order_clause">Window Order Clause</a>.</p>
15284</li>
15285</ul>
15286</li>
15287<li>
15288
15289<p>Return Value:</p>
15290<ul>
15291
15292<li>An integer, greater than or equal to 1.</li>
15293</ul>
15294</li>
15295<li>
15296
15297<p>Example:</p>
15298<p>For each customer, number all orders by value.</p>
15299
15300<div>
15301<div>
15302<pre class="source">FROM orders AS o
15303LET revenue = ROUND((
15304 FROM o.items
15305 SELECT VALUE SUM(qty * price)
15306)[0], 2)
15307SELECT o.custid, o.orderno,
15308ROW_NUMBER() OVER (
15309 PARTITION BY o.custid
15310 ORDER BY revenue
15311) AS `row`;
15312</pre></div></div>
15313</li>
15314<li>
15315
15316<p>The expected result is:</p>
15317
15318<div>
15319<div>
15320<pre class="source">[
15321 {
15322 &quot;row&quot;: 1,
15323 &quot;custid&quot;: &quot;C13&quot;,
15324 &quot;orderno&quot;: 1009
15325 },
15326 {
15327 &quot;row&quot;: 2,
15328 &quot;custid&quot;: &quot;C13&quot;,
15329 &quot;orderno&quot;: 1007
15330 },
15331 {
15332 &quot;row&quot;: 3,
15333 &quot;custid&quot;: &quot;C13&quot;,
15334 &quot;orderno&quot;: 1008
15335 },
15336 {
15337 &quot;row&quot;: 4,
15338 &quot;custid&quot;: &quot;C13&quot;,
15339 &quot;orderno&quot;: 1002
15340 },
15341 {
15342 &quot;row&quot;: 1,
15343 &quot;custid&quot;: &quot;C31&quot;,
15344 &quot;orderno&quot;: 1003
15345 },
15346 {
15347 &quot;row&quot;: 1,
15348 &quot;custid&quot;: &quot;C35&quot;,
15349 &quot;orderno&quot;: 1004
15350 },
15351 {
15352 &quot;row&quot;: 1,
15353 &quot;custid&quot;: &quot;C37&quot;,
15354 &quot;orderno&quot;: 1005
15355 },
15356 {
15357 &quot;row&quot;: 1,
15358 &quot;custid&quot;: &quot;C41&quot;,
15359 &quot;orderno&quot;: 1001
15360 },
15361 {
15362 &quot;row&quot;: 2,
15363 &quot;custid&quot;: &quot;C41&quot;,
15364 &quot;orderno&quot;: 1006
15365 }
15366]
15367</pre></div></div>
15368</li>
15369</ul><hr />
15370<p><a name="fn_1" id="fn_1">1</a>. If the query contains the GROUP BY clause or any <a href="#AggregateFunctions">aggregate functions</a>, this expression must only depend on GROUP BY expressions or aggregate functions.</p></div></div>
15371 </div>
15372 </div>
15373 </div>
15374 <hr/>
15375 <footer>
15376 <div class="container-fluid">
15377 <div class="row-fluid">
15378<div class="row-fluid">Apache AsterixDB, AsterixDB, Apache, the Apache
15379 feather logo, and the Apache AsterixDB project logo are either
15380 registered trademarks or trademarks of The Apache Software
15381 Foundation in the United States and other countries.
15382 All other marks mentioned may be trademarks or registered
15383 trademarks of their respective owners.
15384 </div>
15385 </div>
15386 </div>
15387 </footer>
15388 </body>
15389</html>