Skip to main content

date_interval

Definition​

A date_interval is a date attribute defined as the interval between a start and end date.

Usage​

Date interval attributes must be defined using a definition specifying the start and end date with the interval function. They currently cannot be defined using sql, in contrast to other attributes.

Let's consider the example of modeling music festivals, which start at a certain date and end at another:

kb {

    class MusicFestival {
        # Use the interval by default if not otherwise specified, instead of StartDate or EndDate
        event_date: Date

        ...

        date StartDate { ... }
        date EndDate { ... }

        date_interval Date {
            name.en: "Festival Date"

            definition: "interval(this.StartDate, this.EndDate)"

            # Must be the same as StartDate and EndDate
            datetime_format: DayFormat
        }
    }
}

Note that both the start and end are inclusive, meaning that they are inside the interval. If the end should be exclusive, subtract one day (or the appropriate granularity). The start and end date may be both the same, meaning that only that single date is in the interval.

caution

You should define a onto.CalendarTable somewhere in the knowledge graph to use date intervals. Otherwise questions like grouping by month or year, e.g. "Number of festivals per month", will not work.

Behavior​

Date intervals can be used in most questions where date attributes can be used, e.g. in questions like "How many festivals were there this year" or "Number of festivals per year". However, they come with special behavior:

  • A date interval is considered to be in another date if there is an overlap between the two
    • For example, the date interval from 2019-12-01 to 2020-01-01 will be considered to be in both 2019 and 2020
  • Sorting ascendingly (or descendingly) will be based on the start (or end) date respectively
    • For example, asking for "first festival" will return the festival that started earliest, while "most recent festival" will return the festival that ended last
  • When grouping by a date interval, it will appear in each group that has an overlap with the interval
    • For example, asking "number of festivals per month" will count a festival towards all overlapping months, i.e. a festival starting at the end of one month and ending at the start of the next month will be counted towards both months
    • An onto.CalendarTable needs to be defined somewhere in the knowledge graph for this to work, such that all dates inside the interval can be filled in
  • Empty intervals or intervals where the end date comes before the start date are currently not supported, the behavior is undefined
info

Date intervals are prone to double counting, e.g. the same festival being counted towards two different years. If this is not intended, consider using a simple date attribute instead, choosing a single date that the class should be counted at, e.g. the start, end or midpoint date of the interval.