Temporal relationships

The Spatiotemporal Join joins records in one DataFrame to records in another DataFrame based on spatial, temporal, or attribute relationships, or a combination of those relationships. For example, if two records occur within one hour of each other, they will be joined.

Records in time-enabled DataFrames can be represented in one of the following two ways:

  • Instant—A single moment in time.
  • Interval—A duration of time with a start and end time.

Temporal relationships are based on ISO19108 - Temporal Schema.

Target and join DataFrame

A temporal join matches records from the target DataFrame to the join DataFrame based on the record's placement or occurrence in time.

The following legend applies to all examples in this topic:

  • Target DataFrame time—Green
  • Join DataFrame time—Blue

Time types and supported relationships

The following table lists the supported temporal relationships for a temporal join between time types (for example, joining time intervals to time instants):

Instant and instantInstant and intervalInterval and instantInterval and interval
Equals
During
Contains
Finishes
Finished by
Meets
Met by
Overlaps
Overlapped by
Starts
Started by
Intersects
Near
Near before
Near after
Full supportPartial supportNo support

    Equals

    Two times are considered equal if their instants or intervals are identical. The times of both the target and join DataFrame must be of the same type to be considered equal—both instant or both interval times.

    Temporal equals relationship

    During

    When a target time occurs between the start and end of the join time interval, the target time is during the join time. This is the opposite of the Contains temporal relationship operator. During is supported when the join time is an interval.

    Temporal during relationship

    Contains

    When a join record time occurs between the start and end of the target time interval, the target time contains the join time. This is the opposite of the During temporal relationship operator. Contains is supported when the target record is an interval.

    Temporal contains relationship

    Finishes

    When a target time ends at the same time as a join time, and the target time started after the join time, the target time finishes the join time. This is the complement of the Finished by temporal relationship operator and the opposite of the Starts temporal relationship operator. Finishes is supported when the join record is an interval.

    Temporal finishes relationship

    Finished by

    When a join record time ends at the same time as a target time, and the join time started after the target time, the target time is finished by the join time. This is the complement of the Finishes temporal relationship operator and the opposite of the Started by temporal relationship operator. Finished by is supported when the target record is an interval.

    Temporal finished by relationship

    Meets

    When a target time interval end is equal to the join time interval start, the target time meets the join time. This is the complement of the Met by temporal relationship operator. Meets is supported when the join and target times are intervals.

    Temporal meets relationship

    Met by

    When a target time interval start is equal to the join time interval end, the target time is met by the join time. This is the complement of the Meets temporal relationship operator. Met by is supported when the join and target times are intervals.

    Temporal met by relationship

    Overlaps

    When a target time interval starts and ends before the start and end of the join time interval, the target time overlaps the join time. This is the complement of the Overlapped by temporal relationship operator. Overlaps is supported when the join and target times are intervals.

    Temporal overlaps relationship

    Overlapped by

    When a target time interval starts and ends after the start and end time of the join time interval, the target time is overlapped by the join time. This is the complement of the Overlaps temporal relationship. Overlapped by is supported when the join and target times are intervals.

    Temporal overlapped by relationship

    Starts

    When a target time starts at the same time as the join time interval start and ends before the join time interval ends, the target time starts the join time. This is the complement of the Started by temporal relationship operator and the opposite of the Finishes temporal relationship operator. Starts is supported when the join time is an interval.

    Temporal starts relationship

    Started by

    When a target interval time starts at the same time as the join time and ends after the join time, the target time is started by the join time. This is the complement of the Starts temporal relationship operator and the opposite of the Finished by temporal relationship operator. Started by is supported when the target time is an interval.

    Temporal started by relationship

    Intersects

    When any part of a target time occurs at the same time as the join time, the target time intersects the join time. The Intersects operator is a combination of all the other types of temporal relationships.

    Temporal intersects relationship

    Near

    When a target time is within a specified range of time from the join time, the target time is near the join time. Using a user-specified temporal distance (for example, 1 month), an Intersects relationship operator is applied with the temporal distance added to both ends of the join time.

    Temporal near relationship

    Near before

    When a target time is within a specified range of time and occurs before the join time, the target time is near before the join time. Using a user-specified temporal distance (for example, 1 month), an Intersects relationship operator is applied with the temporal distance added to the beginning of the join time.

    Temporal near before relationship

    Near after

    When a target time is within a specified range of time and occurs after the join time, the target time is near after the join time. Using a user-specified temporal distance (for example, 1 month), an Intersects relationship operator is applied with the temporal distance added to the end of the join time.

    Temporal near after relationship

    What's next?

    Learn more about temporal relationships:

    Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.