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