Tutorial 3: Intervals & Allen's Temporal Algebra

Open inAnthropic

Series: Time Processing Overview | Tutorial 1: Dates | Tutorial 2: Durations | Tutorial 3 | Tutorial 4: Creative Patterns

What you will learn

By the end of this tutorial you will be able to:

  • Construct and deconstruct xdd:dateTimeInterval values
  • Explain the difference between half-open and inclusive interval representations
  • Use interval_relation_typed to classify or validate how two periods relate
  • Name and recognize all 13 Allen interval relations
  • Verify that a set of periods tiles a larger period without gaps or overlaps

Prerequisites

  • Completed Tutorial 2: Durations
  • A running TerminusDB instance (optional — the walkthrough simulates every query)

Interactive demo
Open walkthrough

Part 1: What Is an Interval?

An interval is a pair of dates that defines a period: a start and an end. In TerminusDB, intervals are stored as xdd:dateTimeInterval values using ISO 8601 notation: "start/end".

Critically, TerminusDB intervals are half-open: the start is inclusive, the end is exclusive. "2025-01-01T00:00:00Z/2025-04-01T00:00:00Z" means "from January 1 up to but not including April 1" — which is exactly Q1 2025.

Step 1: Construct an interval from two dates

What happened: v:q1 is bound to "2025-01-01T00:00:00Z/2025-04-01T00:00:00Z" with type xdd:dateTimeInterval. The inclusive end date 2025-03-31 is stored as the start of the next day, giving the half-open Q1 interval [Jan 1, Apr 1).

Step 2: Deconstruct an interval

interval is bidirectional — give it an interval and it extracts the endpoints. From the typed literal "2025-01-01/2025-03-31" you get v:start = 2025-01-01T00:00:00Z and v:end = 2025-04-01T00:00:00Z (the stored exclusive end).

Date-only output? Deconstruction always returns xsd:dateTime endpoints. If you need plain dates, use typecast(v:start, "xsd:date", ...) or cast the whole interval to xdd:dateRange.

Step 3: Interval from start + duration


Part 2: Allen's 13 Interval Relations

Given any two intervals, exactly one of 13 relationships holds. This is Allen's Interval Algebra — a complete classification of how two time periods can relate.

interval_relation_typed(Relation, X, Y) works in two modes:

  • Validation: Give it a specific relation name → succeeds if that relation holds
  • Classification: Give it a variable → binds to the relation that holds

The 13 relations at a glance

RelationX relative to YTimeline
beforeX ends before Y starts (gap between)XX___YY
afterX starts after Y endsYY___XX
meetsX ends exactly where Y startsXXYY
met_byX starts exactly where Y endsYYXX
overlapsX starts first, they share a middle, Y ends lastXXXX / __YYYY
overlapped_byY starts first, X ends lastYYYY / __XXXX
startsX and Y start together, X ends firstXX / YYYY
started_byX and Y start together, Y ends firstXXXX / YY
duringX is entirely inside Y_XX_ / YYYY
containsY is entirely inside XXXXX / _YY_
finishesX and Y end together, X starts later__XX / YYYY
finished_byX and Y end together, Y starts laterXXXX / __YY
equalsSame start, same endXXXX / YYYY

Step 4: Validate — Do Q1 and Q2 meet?

What happened: One result — the meets relation holds. Q1's end (Apr 1) equals Q2's start (Apr 1). No gap, no overlap.

Step 5: Classify — What is the relation?

Step 6: Before — with a gap

Step 7: Overlaps

Step 8: During — containment

Step 9: Equals


Part 3: Practical Application — Verify Fiscal Quarters

The real power of Allen's algebra: verify that a set of periods forms a correct partition.

Step 10: Quarters meet each other

One result means all three meets checks passed. Your quarters tile cleanly.

Step 11: Q1 starts the fiscal year

Step 12: Q4 finishes the fiscal year

Step 13: Non-adjacent quarters — before


Part 4: DateTime Intervals — Sub-Day Precision

Intervals work with xsd:dateTime too, not just dates.

Step 14: Shift scheduling

Step 15: Overlapping meetings


Part 5: The 5-Argument Form — interval_relation

When your endpoints are already in separate variables (not packaged as intervals), use the 5-argument form:

When to use which form

Your dataUseWhy
xdd:dateTimeInterval valuesinterval_relation_typed(rel, x, y)Cleaner — no unpacking
Separate start/end variablesinterval_relation(rel, xs, xe, ys, ye)No need to construct intervals

Self-Check

  1. What type is "2025-01-01/2025-03-31"? Is April 1 included?
  2. If interval_relation_typed("meets", Q1, Q2) succeeds, what can you say about the boundary?
  3. How many Allen relations exist? Can more than one hold for the same pair?
  4. What is the relation between Q2 and the fiscal year [Jan 1, Jan 1 next year)?
  5. How would you detect that two audit periods overlap?

What You Learned

ConceptKey Point
xdd:dateTimeIntervalHalf-open [start, end) encoded as "start/end"
intervalBidirectional: construct ↔ deconstruct
interval_relation_typed3-argument Allen's algebra on interval values
Validation modeGround relation → succeeds/fails
Classification modeVariable relation → binds to the one that holds
13 Allen relationsExactly one always holds for any two intervals
meetsAdjacent periods with no gap — the partition test
starts / finishesSub-period shares a boundary with the outer
during / containsFull containment

Next

Tutorial 4: Creative Temporal Patterns →

Was this helpful?