blob: 9c55f3da00418316b554862d50fdaac3187dad97 [file] [log] [blame]
Ian Maxone2b799e2015-11-24 18:20:03 -08001<!DOCTYPE html>
2<!--
3 | Generated by Apache Maven Doxia at 2015-11-24
4 | Rendered using Apache Maven Fluido Skin 1.3.0
5-->
6<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
7 <head>
8 <meta charset="UTF-8" />
9 <meta name="viewport" content="width=device-width, initial-scale=1.0" />
10 <meta name="Date-Revision-yyyymmdd" content="20151124" />
11 <meta http-equiv="Content-Language" content="en" />
12 <title>AsterixDB &#x2013; AsterixDB Temporal Functions: Allens Relations</title>
13 <link rel="stylesheet" href="../css/apache-maven-fluido-1.3.0.min.css" />
14 <link rel="stylesheet" href="../css/site.css" />
15 <link rel="stylesheet" href="../css/print.css" media="print" />
16
17
18 <script type="text/javascript" src="../js/apache-maven-fluido-1.3.0.min.js"></script>
19
20
21
Ian Maxone2b799e2015-11-24 18:20:03 -080022
Ian Maxone2b799e2015-11-24 18:20:03 -080023
24 </head>
25 <body class="topBarDisabled">
26
27
28
29
30 <div class="container-fluid">
31 <div id="banner">
32 <div class="pull-left">
33 <a href="http://asterixdb.apache.org/" id="bannerLeft">
34 <img src="../images/asterixlogo.png" alt="AsterixDB"/>
35 </a>
36 </div>
37 <div class="pull-right"> </div>
38 <div class="clear"><hr/></div>
39 </div>
40
41 <div id="breadcrumbs">
42 <ul class="breadcrumb">
43
44
45 <li id="publishDate">Last Published: 2015-11-24</li>
46
47
48
49 <li id="projectVersion" class="pull-right">Version: 0.8.7-incubating</li>
50
51 <li class="divider pull-right">|</li>
52
53 <li class="pull-right"> <a href="../index.html" title="Documentation Home">
54 Documentation Home</a>
55 </li>
56
57 </ul>
58 </div>
59
60
61 <div class="row-fluid">
62 <div id="leftColumn" class="span3">
63 <div class="well sidebar-nav">
64
65
66 <ul class="nav nav-list">
67 <li class="nav-header">Documentation</li>
68
69 <li>
70
71 <a href="../install.html" title="Installing and Managing AsterixDB using Managix">
72 <i class="none"></i>
73 Installing and Managing AsterixDB using Managix</a>
74 </li>
75
76 <li>
77
78 <a href="../yarn.html" title="Deploying AsterixDB using YARN">
79 <i class="none"></i>
80 Deploying AsterixDB using YARN</a>
81 </li>
82
83 <li>
84
85 <a href="../aql/primer.html" title="AsterixDB 101: An ADM and AQL Primer">
86 <i class="none"></i>
87 AsterixDB 101: An ADM and AQL Primer</a>
88 </li>
89
90 <li>
91
92 <a href="../aql/primer-sql-like.html" title="AsterixDB 101: An ADM and AQL Primer (For SQL Fans)">
93 <i class="none"></i>
94 AsterixDB 101: An ADM and AQL Primer (For SQL Fans)</a>
95 </li>
96
97 <li>
98
99 <a href="../aql/js-sdk.html" title="AsterixDB Javascript SDK">
100 <i class="none"></i>
101 AsterixDB Javascript SDK</a>
102 </li>
103
104 <li>
105
106 <a href="../aql/datamodel.html" title="Asterix Data Model (ADM)">
107 <i class="none"></i>
108 Asterix Data Model (ADM)</a>
109 </li>
110
111 <li>
112
113 <a href="../aql/manual.html" title="Asterix Query Language (AQL)">
114 <i class="none"></i>
115 Asterix Query Language (AQL)</a>
116 </li>
117
118 <li>
119
120 <a href="../aql/functions.html" title="AQL Functions">
121 <i class="none"></i>
122 AQL Functions</a>
123 </li>
124
125 <li class="active">
126
127 <a href="#"><i class="none"></i>AQL Allen's Relations Functions</a>
128 </li>
129
130 <li>
131
132 <a href="../aql/similarity.html" title="AQL Support of Similarity Queries">
133 <i class="none"></i>
134 AQL Support of Similarity Queries</a>
135 </li>
136
137 <li>
138
139 <a href="../aql/externaldata.html" title="Accessing External Data">
140 <i class="none"></i>
141 Accessing External Data</a>
142 </li>
143
144 <li>
145
146 <a href="../feeds/tutorial.html" title="Support for Data Ingestion in AsterixDB">
147 <i class="none"></i>
148 Support for Data Ingestion in AsterixDB</a>
149 </li>
150
151 <li>
152
153 <a href="../udf.html" title="Support for User Defined Functions in AsterixDB">
154 <i class="none"></i>
155 Support for User Defined Functions in AsterixDB</a>
156 </li>
157
158 <li>
159
160 <a href="../aql/filters.html" title="Filter-Based LSM Index Acceleration">
161 <i class="none"></i>
162 Filter-Based LSM Index Acceleration</a>
163 </li>
164
165 <li>
166
167 <a href="../api.html" title="HTTP API to AsterixDB">
168 <i class="none"></i>
169 HTTP API to AsterixDB</a>
170 </li>
171 </ul>
172
173
174
175 <hr class="divider" />
176
177 <div id="poweredBy">
178 <div class="clear"></div>
179 <div class="clear"></div>
180 <div class="clear"></div>
181 <a href="https://code.google.com/p/hyracks/" title="Hyracks" class="builtBy">
182 <img class="builtBy" alt="Hyracks" src="../images/hyrax_ts.png" />
183 </a>
184 </div>
185 </div>
186 </div>
187
188
189 <div id="bodyColumn" class="span9" >
190
191 <!-- ! Licensed to the Apache Software Foundation (ASF) under one
192 ! or more contributor license agreements. See the NOTICE file
193 ! distributed with this work for additional information
194 ! regarding copyright ownership. The ASF licenses this file
195 ! to you under the Apache License, Version 2.0 (the
196 ! "License"); you may not use this file except in compliance
197 ! with the License. You may obtain a copy of the License at
198 !
199 ! http://www.apache.org/licenses/LICENSE-2.0
200 !
201 ! Unless required by applicable law or agreed to in writing,
202 ! software distributed under the License is distributed on an
203 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
204 ! KIND, either express or implied. See the License for the
205 ! specific language governing permissions and limitations
206 ! under the License.
207 ! --><h1>AsterixDB Temporal Functions: Allen&#x2019;s Relations</h1>
208<div class="section">
209<h2><a name="Table_of_Contents"></a><a name="toc" id="toc">Table of Contents</a></h2>
210
211<ul>
212
213<li><a href="#AboutAllensRelations">About Allen&#x2019;s Relations</a></li>
214
215<li><a href="#AllensRelatonsFunctions">Allen&#x2019;s Relations Functions</a></li>
216</ul></div>
217<div class="section">
218<h2><a name="About_Allens_Relations_Back_to_TOC"></a><a name="AboutAllensRelations" id="AboutAllensRelations">About Allen&#x2019;s Relations</a> <font size="4"><a href="#toc">[Back to TOC]</a></font></h2>
219<p>AsterixDB supports Allen&#x2019;s relations over interval types. Allen&#x2019;s relations are also called Allen&#x2019;s interval algebra. There are totally 13 base relations described by this algebra, and all of them are supported in AsterixDB (note that <tt>interval-equals</tt> is supported by the <tt>=</tt> comparison symbol so there is no extra function for it). </p>
220<p>A detailed description of Allen&#x2019;s relations can be found from its <a class="externalLink" href="http://en.wikipedia.org/wiki/Allen&apos;s_interval_algebra">wikipedia entry</a>. </p></div>
221<div class="section">
222<h2><a name="Allens_Relations_Functions_Back_to_TOC"></a><a name="AllensRelatonsFunctions" id="AllensRelatonsFunctions">Allen&#x2019;s Relations Functions</a> <font size="4"><a href="#toc">[Back to TOC]</a></font></h2>
223<div class="section">
224<h3><a name="interval-before_interval-after"></a>interval-before, interval-after</h3>
225
226<ul>
227
228<li>
229<p>Syntax:</p>
230
231<div class="source">
232<div class="source">
233<pre>interval-before(interval1, interval2)
234interval-after(interval1, interval2)
235</pre></div></div></li>
236
237<li>
238<p>These two functions check whether an interval happens before/after another interval. </p></li>
239
240<li>Arguments:
241
242<ul>
243
244<li><tt>interval1</tt>, <tt>interval2</tt>: two intervals to be compared</li>
245 </ul></li>
246
247<li>
248<p>Return Value:</p>
249<p>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>. If any of the two inputs is <tt>null</tt>, <tt>null</tt> is returned.</p></li>
250
251<li>
252<p>Examples:</p>
253
254<div class="source">
255<div class="source">
256<pre>let $itv1 := interval-from-date(&quot;2000-01-01&quot;, &quot;2005-01-01&quot;)
257let $itv2 := interval-from-date(&quot;2005-05-01&quot;, &quot;2012-09-09&quot;)
258return {&quot;interval-before&quot;: interval-before($itv1, $itv2), &quot;interval-after&quot;: interval-after($itv2, $itv1)}
259</pre></div></div></li>
260
261<li>
262<p>The expected result is:</p>
263
264<div class="source">
265<div class="source">
266<pre>{ &quot;interval-before&quot;: true, &quot;interval-after&quot;: true }
267</pre></div></div></li>
268</ul></div>
269<div class="section">
270<h3><a name="interval-covers_interval-covered-by"></a>interval-covers, interval-covered-by</h3>
271
272<ul>
273
274<li>
275<p>Syntax:</p>
276
277<div class="source">
278<div class="source">
279<pre>interval-covers(interval1, interval2)
280interval-covered-by(interval1, interval2)
281</pre></div></div></li>
282
283<li>
284<p>These two functions check whether one interval covers the other interval.</p></li>
285
286<li>Arguments:
287
288<ul>
289
290<li><tt>interval1</tt>, <tt>interval2</tt>: two intervals to be compared</li>
291 </ul></li>
292
293<li>
294<p>Return Value:</p>
295<p>A <tt>boolean</tt> value. Specifically, <tt>interval-covers(interval1, interval2)</tt> is true if and only if</p>
296
297<div class="source">
298<div class="source">
299<pre>interval1.start &lt;= interval2.start
300AND interval1.end &gt;= interval2.end
301</pre></div></div>
302<p><tt>interval-covered-by(interval1, interval2)</tt> is true if and only if</p>
303
304<div class="source">
305<div class="source">
306<pre>interval2.start &lt;= interval1.start
307AND interval2.end &gt;= interval1.end
308</pre></div></div>
309<p>For both functions, if any of the two inputs is <tt>null</tt>, <tt>null</tt> is returned.</p></li>
310
311<li>
312<p>Examples:</p>
313
314<div class="source">
315<div class="source">
316<pre>let $itv1 := interval-from-date(&quot;2000-01-01&quot;, &quot;2005-01-01&quot;)
317let $itv2 := interval-from-date(&quot;2000-03-01&quot;, &quot;2004-09-09&quot;)
318let $itv3 := interval-from-date(&quot;2006-08-01&quot;, &quot;2007-03-01&quot;)
319let $itv4 := interval-from-date(&quot;2004-09-10&quot;, &quot;2012-08-01&quot;)
320return {&quot;interval-covers&quot;: interval-covers($itv1, $itv2), &quot;interval-covered-by&quot;: interval-covered-by($itv3, $itv4)}
321</pre></div></div></li>
322
323<li>
324<p>The expected result is:</p>
325
326<div class="source">
327<div class="source">
328<pre>{ &quot;interval-covers&quot;: true, &quot;interval-covered-by&quot;: true }
329</pre></div></div></li>
330</ul></div>
331<div class="section">
332<h3><a name="interval-overlaps_interval-overlapped-by"></a>interval-overlaps, interval-overlapped-by</h3>
333
334<ul>
335
336<li>
337<p>Syntax:</p>
338
339<div class="source">
340<div class="source">
341<pre>interval-overlaps(interval1, interval2)
342interval-overlapped-by(interval1, interval2)
343</pre></div></div></li>
344
345<li>
346<p>These functions check whether two intervals overlap with each other.</p></li>
347
348<li>Arguments:
349
350<ul>
351
352<li><tt>interval1</tt>, <tt>interval2</tt>: two intervals to be compared</li>
353 </ul></li>
354
355<li>
356<p>Return Value:</p>
357<p>A <tt>boolean</tt> value. Specifically, <tt>interval-overlaps(interval1, interval2)</tt> is true if and only if</p>
358
359<div class="source">
360<div class="source">
361<pre>interval1.start &lt; interval2.start
362AND interval2.end &gt; interval1.end
363AND interval1.end &gt; interval2.start
364</pre></div></div>
365<p><tt>interval-overlapped-by(interval1, interval2)</tt> is true if and only if</p>
366
367<div class="source">
368<div class="source">
369<pre>interval2.start &lt; interval1.start
370AND interval1.end &gt; interval2.end
371AND interval2.end &gt; interval1.start
372</pre></div></div>
373<p>For all these functions, if any of the two inputs is <tt>null</tt>, <tt>null</tt> is returned.</p>
374<p>Note that <tt>interval-overlaps</tt> and <tt>interval-overlapped-by</tt> are following the Allen&#x2019;s relations on the definition of overlap.</p></li>
375
376<li>
377<p>Examples:</p>
378
379<div class="source">
380<div class="source">
381<pre>let $itv1 := interval-from-date(&quot;2000-01-01&quot;, &quot;2005-01-01&quot;)
382let $itv2 := interval-from-date(&quot;2004-05-01&quot;, &quot;2012-09-09&quot;)
383let $itv3 := interval-from-date(&quot;2006-08-01&quot;, &quot;2007-03-01&quot;)
384let $itv4 := interval-from-date(&quot;2004-09-10&quot;, &quot;2006-12-31&quot;)
385return {&quot;overlaps&quot;: interval-overlaps($itv1, $itv2),
386 &quot;overlapped-by&quot;: interval-overlapped-by($itv3, $itv4)}
387</pre></div></div></li>
388
389<li>
390<p>The expected result is:</p>
391
392<div class="source">
393<div class="source">
394<pre>{ &quot;overlaps&quot;: true, &quot;overlapped-by&quot;: true }
395</pre></div></div></li>
396</ul></div>
397<div class="section">
398<h3><a name="interval-overlapping"></a>interval-overlapping</h3>
399<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>
400
401<ul>
402
403<li>
404<p>Syntax:</p>
405
406<div class="source">
407<div class="source">
408<pre>interval-overlapping(interval1, interval2)
409</pre></div></div></li>
410
411<li>
412<p>This functions check whether two intervals share any points with each other. </p></li>
413
414<li>Arguments:
415
416<ul>
417
418<li><tt>interval1</tt>, <tt>interval2</tt>: two intervals to be compared</li>
419 </ul></li>
420
421<li>
422<p>Return Value:</p>
423<p>A <tt>boolean</tt> value. Specifically, <tt>interval-overlapping(interval1, interval2)</tt> is true if</p>
424
425<div class="source">
426<div class="source">
427<pre>(interval2.start &gt;= interval1.start
428AND interval2.start &lt; interval1.end)
429OR
430(interval2.end &gt; interval1.start
431AND interval2.end &lt;= interval1.end)
432</pre></div></div>
433<p>If any of the two inputs is <tt>null</tt>, <tt>null</tt> is returned.</p></li>
434
435<li>
436<p>Examples:</p>
437
438<div class="source">
439<div class="source">
440<pre>let $itv1 := interval-from-date(&quot;2000-01-01&quot;, &quot;2005-01-01&quot;)
441let $itv2 := interval-from-date(&quot;2004-05-01&quot;, &quot;2012-09-09&quot;)
442let $itv3 := interval-from-date(&quot;2006-08-01&quot;, &quot;2007-03-01&quot;)
443let $itv4 := interval-from-date(&quot;2004-09-10&quot;, &quot;2006-12-31&quot;)
444return {&quot;overlapping1&quot;: interval-overlapping($itv1, $itv2),
445 &quot;overlapping2&quot;: interval-overlapping($itv3, $itv4)}
446</pre></div></div></li>
447
448<li>
449<p>The expected result is:</p>
450
451<div class="source">
452<div class="source">
453<pre>{ &quot;overlapping1&quot;: true, &quot;overlapping2&quot;: true }
454</pre></div></div></li>
455</ul></div>
456<div class="section">
457<h3><a name="interval-meets_interval-met-by"></a>interval-meets, interval-met-by</h3>
458
459<ul>
460
461<li>
462<p>Syntax:</p>
463
464<div class="source">
465<div class="source">
466<pre>interval-meets(interval1, interval2)
467interval-met-by(interval1, interval2)
468</pre></div></div></li>
469
470<li>
471<p>These two functions check whether an interval meets with another interval. </p></li>
472
473<li>Arguments:
474
475<ul>
476
477<li><tt>interval1</tt>, <tt>interval2</tt>: two intervals to be compared</li>
478 </ul></li>
479
480<li>
481<p>Return Value:</p>
482<p>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.</p></li>
483
484<li>
485<p>Examples:</p>
486
487<div class="source">
488<div class="source">
489<pre>let $itv1 := interval-from-date(&quot;2000-01-01&quot;, &quot;2005-01-01&quot;)
490let $itv2 := interval-from-date(&quot;2005-01-01&quot;, &quot;2012-09-09&quot;)
491let $itv3 := interval-from-date(&quot;2006-08-01&quot;, &quot;2007-03-01&quot;)
492let $itv4 := interval-from-date(&quot;2004-09-10&quot;, &quot;2006-08-01&quot;)
493return {&quot;meets&quot;: interval-meets($itv1, $itv2), &quot;metby&quot;: interval-met-by($itv3, $itv4)}
494</pre></div></div></li>
495
496<li>
497<p>The expected result is:</p>
498
499<div class="source">
500<div class="source">
501<pre>{ &quot;meets&quot;: true, &quot;metby&quot;: true }
502</pre></div></div></li>
503</ul></div>
504<div class="section">
505<h3><a name="interval-starts_interval-started-by"></a>interval-starts, interval-started-by</h3>
506
507<ul>
508
509<li>
510<p>Syntax:</p>
511
512<div class="source">
513<div class="source">
514<pre>interval-starts(interval1, interval2)
515interval-started-by(interval1, interval2)
516</pre></div></div></li>
517
518<li>
519<p>These two functions check whether one interval starts with the other interval.</p></li>
520
521<li>Arguments:
522
523<ul>
524
525<li><tt>interval1</tt>, <tt>interval2</tt>: two intervals to be compared</li>
526 </ul></li>
527
528<li>
529<p>Return Value:</p>
530<p>A <tt>boolean</tt> value. Specifically, <tt>interval-starts(interval1, interval2)</tt> returns true if and only if</p>
531
532<div class="source">
533<div class="source">
534<pre>interval1.start = interval2.start
535AND interval1.end &lt;= interval2.end
536</pre></div></div>
537<p><tt>interval-started-by(interval1, interval2)</tt> returns true if and only if</p>
538
539<div class="source">
540<div class="source">
541<pre>interval1.start = interval2.start
542AND interval2.end &lt;= interval1.end
543</pre></div></div>
544<p>For both functions, if any of the two inputs is <tt>null</tt>, <tt>null</tt> is returned.</p></li>
545
546<li>
547<p>Examples:</p>
548
549<div class="source">
550<div class="source">
551<pre>let $itv1 := interval-from-date(&quot;2000-01-01&quot;, &quot;2005-01-01&quot;)
552let $itv2 := interval-from-date(&quot;2000-01-01&quot;, &quot;2012-09-09&quot;)
553let $itv3 := interval-from-date(&quot;2006-08-01&quot;, &quot;2007-03-01&quot;)
554let $itv4 := interval-from-date(&quot;2006-08-01&quot;, &quot;2006-08-01&quot;)
555return {&quot;interval-starts&quot;: interval-starts($itv1, $itv2), &quot;interval-started-by&quot;: interval-started-by($itv3, $itv4)}
556</pre></div></div></li>
557
558<li>
559<p>The expected result is:</p>
560
561<div class="source">
562<div class="source">
563<pre>{ &quot;interval-starts&quot;: true, &quot;interval-started-by&quot;: true }
564</pre></div></div></li>
565</ul></div>
566<div class="section">
567<h3><a name="interval-ends_interval-ended-by"></a>interval-ends, interval-ended-by</h3>
568
569<ul>
570
571<li>
572<p>Syntax:</p>
573
574<div class="source">
575<div class="source">
576<pre>interval-ends(interval1, interval2)
577interval-ended-by(interval1, interval2)
578</pre></div></div></li>
579
580<li>
581<p>These two functions check whether one interval ends with the other interval.</p></li>
582
583<li>Arguments:
584
585<ul>
586
587<li><tt>interval1</tt>, <tt>interval2</tt>: two intervals to be compared</li>
588 </ul></li>
589
590<li>
591<p>Return Value:</p>
592<p>A <tt>boolean</tt> value. Specifically, <tt>interval-ends(interval1, interval2)</tt> returns true if and only if</p>
593
594<div class="source">
595<div class="source">
596<pre>interval1.end = interval2.end
597AND interval1.start &gt;= interval2.start
598</pre></div></div>
599<p><tt>interval-ended-by(interval1, interval2)</tt> returns true if and only if</p>
600
601<div class="source">
602<div class="source">
603<pre>interval2.end = interval1.end
604AND interval2.start &gt;= interval1.start
605</pre></div></div>
606<p>For both functions, if any of the two inputs is <tt>null</tt>, <tt>null</tt> is returned.</p></li>
607
608<li>
609<p>Examples:</p>
610
611<div class="source">
612<div class="source">
613<pre>let $itv1 := interval-from-date(&quot;2000-01-01&quot;, &quot;2005-01-01&quot;)
614let $itv2 := interval-from-date(&quot;1998-01-01&quot;, &quot;2005-01-01&quot;)
615let $itv3 := interval-from-date(&quot;2006-08-01&quot;, &quot;2007-03-01&quot;)
616let $itv4 := interval-from-date(&quot;2006-09-10&quot;, &quot;2007-03-01&quot;)
617return {&quot;interval-ends&quot;: interval-ends($itv1, $itv2), &quot;interval-ended-by&quot;: interval-ended-by($itv3, $itv4) }
618</pre></div></div></li>
619
620<li>
621<p>The expected result is:</p>
622
623<div class="source">
624<div class="source">
625<pre>{ &quot;interval-ends&quot;: true, &quot;interval-ended-by&quot;: true }
626</pre></div></div></li>
627</ul></div></div>
628 </div>
629 </div>
630 </div>
631
632 <hr/>
633
634 <footer>
635 <div class="container-fluid">
636 <div class="row span12">Copyright &copy; 2015
637 <a href="http://www.apache.org/">The Apache Software Foundation</a>.
638 All Rights Reserved.
639
640 </div>
641
642 <?xml version="1.0" encoding="UTF-8"?>
643<div class="row-fluid">Apache AsterixDB, AsterixDB, Apache, the Apache
644 feather logo, and the Apache AsterixDB project logo are either
645 registered trademarks or trademarks of The Apache Software
646 Foundation in the United States and other countries.
647 All other marks mentioned may be trademarks or registered
648 trademarks of their respective owners.</div>
649
650
651 </div>
652 </footer>
653 </body>
654</html>