> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ocient.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Spatiotemporal Operators

export const OcientGeo = "OcientGeo™";

{OcientGeo} spatiotemporal operators perform calculations on geospatial data using an array of TIMESTAMP arguments.

## ST\_LONGESTLINE

With the specified two `LINESTRING-TIMESTAMP ARRAY` pairs, this function returns a two-point `LINESTRING` that represents the maximum distance between points at a concurrent time.

If the two `LINESTRING` values do not overlap temporally, this function returns NULL.

**Syntax**

```sql SQL theme={null}
ST_LONGESTLINE(linestring1, ts_arr1, linestring2, ts_arr2 [, use_spheroid] )
```

| **Argument**   | **Data** **Type** | **Description**                                                                                                                                  |
| -------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `linestring1`  | `LINESTRING`      | A geospatial object to be evaluated for its maximum cotemporal distance from `linestring2`.                                                      |
| `ts_arr1`      | `TIMESTAMP ARRAY` | A timestamp array that is paired with `linestring1`.<br />Behavior is undefined if this timestamp array is not monotonically increasing.         |
| `linestring2`  | `LINESTRING`      | A geospatial object to be evaluated for its maximum cotemporal distance from `linestring1`.                                                      |
| `ts_arr2`      | `TIMESTAMP ARRAY` | A timestamp array that is paired with `linestring2`.<br />Behavior is undefined if this timestamp array is not monotonically increasing.         |
| `use_spheroid` | `BOOLEAN`         | Optional. <br />If you set this argument to `TRUE`, this function uses a spheroid model instead of a spherical model. <br />Defaults to `FALSE`. |

**Example**

```sql SQL theme={null}
SELECT ST_LONGESTLINE(
        ST_MAKELINE(ST_POINT(0, 0), ST_POINT(0, 12)),
        TIMESTAMP [](
            '2020-07-04 07:00:00.000000000',
            '2020-07-04 11:00:00.000000000'),
        ST_MAKELINE(ST_POINT(0, 0), ST_POINT(8, 0)),
        TIMESTAMP [](
            '2020-07-04 08:00:00.000000000',
            '2020-07-04 10:00:00.000000000'));
```

*Output*: `LINESTRING(0 9, 8 0)`

<Info>
  To use ST\_LONGESTLINE as a spatial function to calculate the longest line between two points, see the [ST\_LONGESTLINE](/spatial-operators#st_longestline)  function.
</Info>

## ST\_LINEGETALLTIMESATPOINT

Returns a timestamp array of all times when the specified `LINESTRING` value intersects the specified `POINT` value. If the line never intersects the point, then the function returns an empty timestamp array.

If the specified inputs are NULL, the function returns NULL.

This function cannot represent intervals of time where the line was stationary at a point, therefore, use this function only for mobile paths. If the path is stationary, use the [ST\_INTERSECTION](#st_intersection) function as it can represent intervals of time spent intersecting a stationary `LINESTRING`.

**Syntax**

```sql SQL theme={null}
ST_LINEGETALLTIMESATPOINT(line, timestamp_arr, point)
```

| **Argument**    | **Data** **Type** | **Description**                                                                                                                                                                                                                                                                |
| --------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `line`          | `LINESTRING`      | A geospatial `LINESTRING` to be evaluated for all time values in the `timestamp_arr` when it intersects the specified `point` value.<br />If this value is empty, the function returns an empty timestamp array.<br />This value must be the same size as the `timestamp_arr`. |
| `timestamp_arr` | `TIMESTAMP ARRAY` | A `TIMESTAMP ARRAY` that is paired with the `line` argument. <br />`timestamp_arr` must be the same size as the `line` value. <br />Behavior is undefined if the timestamp array is not monotonically increasing.                                                              |
| `point`         | `POINT`           | A geospatial point to be evaluated for the time values when the point intersects the `line` value.                                                                                                                                                                             |

**Example**

```sql SQL theme={null}
SELECT ST_LINEGETALLTIMESATPOINT(
        ST_MAKELINE(ST_POINT(0, 0), ST_POINT(4, 0), ST_POINT(0, 0)),
        TIMESTAMP [](
            '2020-07-04 07:00:00.000000000',
            '2020-07-04 08:00:00.000000000',
            '2020-07-04 09:00:00.000000000'),
        ST_POINT(0, 0));
```

*Output*: `TIMESTAMP[]('2020-07-04 07:00:00.000000000', '2020-07-04 09:00:00.000000000')`

## ST\_LINEGETPOINTATTIME

Returns a `POINT` within the bounds of the specified `LINESTRING` that corresponds to the interpolated point at the specified `TIMESTAMP` value.

The specified `TIMESTAMP` value does not need to be an actual value explicitly included in the array. The function interpolates the corresponding point, which means that the function approximates the point coordinates from the surrounding values.

The `LINESTRING` and `TIMESTAMP` array must be the same size. If the timestamp array is not monotonically increasing, the behavior is undefined.

**Syntax**

```sql SQL theme={null}
ST_LINEGETPOINTATTIME(line, timestamp_arr, time_for_point)
```

| **Argument**     | **Data** **Type** | **Description**                                                                                                                                                                                                                                                                                                                                                                       |
| ---------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `line`           | `LINESTRING`      | A geospatial `LINESTRING` to be evaluated for an interpolated point, based on the `time_for_point` value.<br />This value must be the same size as the `timestamp_arr`.                                                                                                                                                                                                               |
| `timestamp_arr`  | `TIMESTAMP ARRAY` | A `TIMESTAMP ARRAY` that is paired with the `line` argument. <br />`timestamp_arr` must be the same size as the `line` value. <br />Behavior is undefined if the timestamp array is not monotonically increasing.                                                                                                                                                                     |
| `time_for_point` | `TIMESTAMP`       | A time value to approximate a `POINT` value on the `line` argument, based on interpolating the values in `timestamp_arr`. <br />If this time value precedes the first value in `timestamp_arr`, the function returns the first `POINT` on `line`. <br />Similarly, if this time value comes after the last value in `timestamp_arr`, the function returns the last `POINT` on `line`. |

**Example**

```sql SQL theme={null}
SELECT ST_LINEGETPOINTATTIME(
    ST_MAKELINE(ST_POINT(0, 0), ST_POINT(4, 0)),
    TIMESTAMP[]('2020-07-04 07:00:00.000000000', '2020-07-04 08:00:00.000000000'),
    TIMESTAMP('2020-07-04 07:30:00.000000000'));
```

*Output*: `POINT(2, 0)`

## ST\_LINEGETTIMEATPOINT

Returns the interpolated time of the specified `POINT` on the specified `LINESTRING` that is paired with a `TIMESTAMP ARRAY`.

The `LINESTRING` and `TIMESTAMP ARRAY` must be the same size.

**Syntax**

```sql SQL theme={null}
ST_LINEGETTIMEATPOINT(line, timestamp_arr, point_for_time)
```

| **Argument**     | **Data** **Type** | **Description**                                                                                                                                                                                                                             |
| ---------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `line`           | `LINESTRING`      | A geospatial line to be evaluated for an interpolated time value based on the `point_for_time` value.<br />This value must be the same size as the `timestamp_arr`.                                                                         |
| `timestamp_arr`  | `TIMESTAMP ARRAY` | A timestamp array that is paired with the `line` argument. <br />`timestamp_arr` must be the same size as the `line` value. <br />Behavior is undefined if the timestamp array is not monotonically increasing.                             |
| `point_for_time` | `POINT`           | A `POINT` value to approximate a `TIMESTAMP` value on the `line` argument, based on interpolating the values in `timestamp_arr`. <br />If `line` intersects this `POINT` value multiple times, then the function returns the earliest time. |

**Example**

```sql SQL theme={null}
SELECT ST_LINEGETTIMEATPOINT(
    ST_MAKELINE(ST_POINT(0, 0), ST_POINT(4, 0)),
    TIMESTAMP[]('2020-07-04 07:00:00.000000000', '2020-07-04 08:00:00.000000000'),
    ST_POINT(2, 0));
```

*Output*: `TIMESTAMP('2020-07-04 07:30:00.000000000')`

## ST\_INTERSECTION

Returns a tuple that represents the intersection of a spatiotemporal `LINESTRING` with a static geography.

If the specified static geography is a `POINT`, the returned value is a tuple that contains a paired `POINT` array and `TIMESTAMP` array.  If the specified static geography is a `LINESTRING` or `POLYGON`, then the returned value is a `LINESTRING` array paired with a two-dimensional `TIMESTAMP` array.

**Syntax**

```sql SQL theme={null}
ST_INTERSECTION(line, timestamp_arr, intersection_point)
```

| **Argument**         | **Data** **Type**                 | **Description**                                                                                                                                                                                                   |
| -------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `line`               | `LINESTRING`                      | A geospatial line to be evaluated for all intersections with the `intersection_point`.<br />If this argument is empty, the function returns NULL.                                                                 |
| `timestamp_arr`      | `TIMESTAMP ARRAY`                 | A `TIMESTAMP ARRAY` that is paired with the `line` argument. <br />`timestamp_arr` must be the same size as the `line` value. <br />Behavior is undefined if the timestamp array is not monotonically increasing. |
| `intersection_point` | `POINT, LINESTRING`, or `POLYGON` | A geographic object to evaluate for all intersections with the `line` argument. <br />If this value is empty, the function returns an empty tuple. If the value is NULL, the function returns NULL.               |

**Example**

```sql SQL theme={null}
SELECT ST_INTERSECTION(
    ST_LINESTRING('LINESTRING(1 1,2 2,3 3)'),
    TIMESTAMP[]('2020-07-04 07:00:00.000000000', '2020-07-04 11:00:00.000000000',
         '2020-07-04 12:00:00.000000000'),
    ST_POLYGON('POLYGON((2 2,3 2,3 3,3 2,2 2))'));
```

*Output*: `TUPLE(LINESTRING[](ST_LINESTRING('LINESTRING(2 2)'), ST_LINESTRING('LINESTRING(3 3)')), ARRAY[ARRAY[TIMESTAMP '2020-07-04 11:00:00.000000000'], ARRAY[TIMESTAMP '2020-07-04 12:00:00.000000000']])`

## ST\_SHORTESTLINE

When you specify two `LINESTRING-TIMESTAMP ARRAY` pairs, this function returns a `LINESTRING` with two points that represents the minimum distance between points at a concurrent time.

If the two linestrings do not overlap temporally, this function returns NULL.

**Syntax**

```sql SQL theme={null}
ST_SHORTESTLINE(linestring1, ts_arr1, linestring2, ts_arr2 [, use_spheroid ])
```

| **Argument**   | **Data** **Type** | **Description**                                                                                                                                  |
| -------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `linestring1`  | `LINESTRING`      | A geospatial object to be evaluated for its minimum cotemporal distance from `linestring2`.                                                      |
| `ts_arr1`      | `TIMESTAMP ARRAY` | A timestamp array that is paired with `linestring1`.                                                                                             |
| `linestring2`  | `LINESTRING`      | A geospatial object to be evaluated for its minimum cotemporal distance from `linestring1`.                                                      |
| `ts_arr2`      | `TIMESTAMP ARRAY` | A timestamp array that is paired with `linestring2`.                                                                                             |
| `use_spheroid` | `BOOLEAN`         | Optional. <br />If you set this argument to `TRUE`, this function uses a spheroid model instead of a spherical model. <br />Defaults to `FALSE`. |

**Example**

```sql SQL theme={null}
SELECT ST_SHORTESTLINE(
    ST_MAKELINE(ST_POINT(0, 0), ST_POINT(4, 0)),
    TIMESTAMP[]('2020-07-04 07:00:00.000000000', '2020-07-04 08:00:00.000000000'),
    ST_MAKELINE(ST_POINT(3, 0), ST_POINT(4, 8)),
    TIMESTAMP[]('2020-07-04 07:00:00.000000000', '2020-07-04 07:30:00.000000000'));
```

*Output*: `LINESTRING(0.09295649430902601 0, 3.0461764508256914 0.37184471667525754)`

<Info>
  To use ST\_SHORTESTLINE as a spatial function to calculate the shortest line between two points, see the [ST\_SHORTESTLINE](/spatial-operators#st_shortestline) function.
</Info>

## Related Links

[Geospatial Data Types](/data-types#geospatial-data-types)

[Spatiotemporal Measurement](/spatiotemporal-measurement)