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

# Track Functions

The following functions are available in both SQL and the native API.

<AccordionGroup>
  <Accordion title="ST_TRACKDURATION([unit,] t)" id="st_trackduration-unit-t" defaultOpen>
    Returns the total time, in the given `unit`, spanned by timestamp values in column
    `t`.  Grouping by *track* ID will return the duration per *track*.

    The duration can be returned in any of the following date/time units:

    * `YEAR`
    * `MONTH`
    * `DAY`
    * `HOUR`
    * `MINUTE`
    * `SECOND`
    * `MILLISECOND`

    The default `unit` is `MILLISECOND`.
  </Accordion>

  <Accordion title="ST_TRACKLENGTH(lat, lon, t[, solution])" id="st_tracklength-lat-lon-t-solution" defaultOpen>
    Returns the total length of the track whose position values are specified by `lat` &
    `lon` and whose ordering is determined by an ascending sort on the timestamp `t`.
    Length can be returned with any of the following solution types:

    <div>
      <table class="table w-full [&_td]:min-w-[150px] [&_th]:text-left [&_td[data-numeric]]:tabular-nums">
        <thead>
          <tr>
            <th>Type</th>
            <th>Description</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td><code>0</code></td>
            <td>2D Euclidean length in degrees</td>
          </tr>

          <tr>
            <td><code>1</code></td>
            <td>(default) Length on a sphere in meters</td>
          </tr>

          <tr>
            <td><code>2</code></td>
            <td>Length on a spheroid in meters</td>
          </tr>
        </tbody>
      </table>
    </div>
  </Accordion>
</AccordionGroup>

## ST\_TRACK\_DWITHIN

The `ST_TRACK_DWITHIN` table function finds tracks that are related, within
spatial or temporal bounds (or both) to the given track(s).  The track(s) to use
as the filter criteria will be specified by the `SEARCH_*` parameters.  The
`TRACK_*` parameters specify the set of tracks to search through for a match.

<Info>
  This function is only available in SQL or in the native API via
  [/execute/sql](/content/api/rest/execute_sql_rest).
</Info>

The basic form of the `ST_TRACK_DWITHIN` function follows.

```sql ST_TRACK_DWITHIN Table Function Syntax theme={null}
SELECT *
FROM TABLE
(
    ST_TRACK_DWITHIN
    (
        TRACK_TABLE => INPUT_TABLE(<table name | select statement>),
        TRACK_ID_COLUMN => < '<column name>' | <column position> >,
        TRACK_X_COLUMN => < '<column name>' | <column position> >,
        TRACK_Y_COLUMN => < '<column name>' | <column position> >,
        TRACK_ORDER_COLUMN => < '<column name>' | <column position> >,
        SEARCH_TABLE => INPUT_TABLE(<table name | select statement>),
        SEARCH_ID_COLUMN => < '<column name>' | <column position> >,
        SEARCH_X_COLUMN => < '<column name>' | <column position> >,
        SEARCH_Y_COLUMN => < '<column name>' | <column position> >,
        SEARCH_ORDER_COLUMN => < '<column name>' | <column position> >,
        [
            SEARCH_XY_DISTANCE => '<spatial distance with unit>',
            SPATIAL_SOLUTION_TYPE => <solution type>,
            SEARCH_TIME_DISTANCE => '<temporal distance with unit>'
        ]
    )
)
```

<AccordionGroup>
  <Accordion title="TRACK_TABLE" id="track_table" defaultOpen>
    Name of the table to search for tracks matching the track(s) specified in the `SEARCH_*` data set.

    To perform a search on the *flights* table, pass the name of the table to `INPUT_TABLE`:

    ```
    INPUT_TABLE(flights)
    ```

    To perform a search on the result of a query, pass the query to `INPUT_TABLE`:

    ```
    INPUT_TABLE
    (
        SELECT * FROM flights_west
        UNION
        SELECT * FROM flights_east
    )
    ```
  </Accordion>

  <Accordion title="TRACK_ID_COLUMN" id="track_id_column" defaultOpen>
    Table to search track column, containing the unique identifier for the track to which each track point
    belongs.
  </Accordion>

  <Accordion title="TRACK_X_COLUMN" id="track_x_column" defaultOpen>
    Table to search track column, containing the longitude value of each track point.
  </Accordion>

  <Accordion title="TRACK_Y_COLUMN" id="track_y_column" defaultOpen>
    Table to search track column, containing the latitude value of each track point.
  </Accordion>

  <Accordion title="TRACK_ORDER_COLUMN" id="track_order_column" defaultOpen>
    Table to search track column, by which the searched track points will be sorted in ascending order.
  </Accordion>

  <Accordion title="SEARCH_TABLE" id="search_table" defaultOpen>
    Name of the search criteria track table, containing the track(s) to be used as the filter criteria
    when searching for matching tracks in the `TRACK_*` data set.

    To match tracks from the *flights\_of\_interest* table, pass the name of the table to `INPUT_TABLE`:

    ```
    INPUT_TABLE(flights_of_interest)
    ```

    To match tracks from the result of a query, pass the query to `INPUT_TABLE`:

    ```
    INPUT_TABLE
    (
        SELECT * FROM flights_of_interest_west
        UNION
        SELECT * FROM flights_of_interest_east
    )
    ```
  </Accordion>

  <Accordion title="SEARCH_ID_COLUMN" id="search_id_column" defaultOpen>
    Search criteria track column, containing the unique identifier for the track to which each track point
    belongs.
  </Accordion>

  <Accordion title="SEARCH_X_COLUMN" id="search_x_column" defaultOpen>
    Search criteria track column, containing the longitude value of each track point.
  </Accordion>

  <Accordion title="SEARCH_Y_COLUMN" id="search_y_column" defaultOpen>
    Search criteria track column, containing the latitude value of each track point.
  </Accordion>

  <Accordion title="SEARCH_ORDER_COLUMN" id="search_order_column" defaultOpen>
    Search criteria track column, by which the filter track points will be sorted in ascending order.
  </Accordion>

  <Accordion title="SEARCH_XY_DISTANCE" id="search_xy_distance" defaultOpen>
    The radius around the given tracks to search for matching tracks.

    <Note>
      This parameter is not applicable when using a `SPATIAL_SOLUTION_TYPE` of `0`.
    </Note>

    <div>
      <table class="table w-full [&_td]:min-w-[150px] [&_th]:text-left [&_td[data-numeric]]:tabular-nums">
        <thead>
          <tr>
            <th>Unit</th>
            <th>Description</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td><code>f</code></td>
            <td>Feet</td>
          </tr>

          <tr>
            <td><code>ki</code></td>
            <td>Kilometers</td>
          </tr>

          <tr>
            <td><code>m</code></td>
            <td>(default) Meters</td>
          </tr>

          <tr>
            <td><code>mi</code></td>
            <td>Miles</td>
          </tr>
        </tbody>
      </table>
    </div>
  </Accordion>

  <Accordion title="SPATIAL_SOLUTION_TYPE" id="spatial_solution_type" defaultOpen>
    Spatial match solution type; any of the following:

    <div>
      <table class="table w-full [&_td]:min-w-[150px] [&_th]:text-left [&_td[data-numeric]]:tabular-nums">
        <thead>
          <tr>
            <th>Type</th>
            <th>Description</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td><code>0</code></td>
            <td>(default) 2D Euclidean length in degrees</td>
          </tr>

          <tr>
            <td><code>1</code></td>
            <td>Length on a sphere, returned in units specified by <code>SEARCH\_XY\_DISTANCE</code></td>
          </tr>

          <tr>
            <td><code>2</code></td>
            <td>Length on a spheroid, returned in units specified by <code>SEARCH\_XY\_DISTANCE</code></td>
          </tr>
        </tbody>
      </table>
    </div>
  </Accordion>

  <Accordion title="SEARCH_TIME_DISTANCE" id="search_time_distance" defaultOpen>
    The maximum allowable time difference between a search criteria track's point and a matched track's
    points.  The time can use any of the following suffices for units:

    <div>
      <table class="table w-full [&_td]:min-w-[150px] [&_th]:text-left [&_td[data-numeric]]:tabular-nums">
        <thead>
          <tr>
            <th>Unit</th>
            <th>Description</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td><code>ms</code></td>
            <td>Milliseconds</td>
          </tr>

          <tr>
            <td><code>s</code></td>
            <td>(default) Seconds</td>
          </tr>

          <tr>
            <td><code>m</code></td>
            <td>Minutes</td>
          </tr>

          <tr>
            <td><code>h</code></td>
            <td>Hours</td>
          </tr>

          <tr>
            <td><code>d</code></td>
            <td>Days</td>
          </tr>

          <tr>
            <td><code>w</code></td>
            <td>Weeks</td>
          </tr>

          <tr>
            <td><code>months</code></td>
            <td>Months</td>
          </tr>

          <tr>
            <td><code>y</code></td>
            <td>Years</td>
          </tr>
        </tbody>
      </table>
    </div>
  </Accordion>
</AccordionGroup>

To see the matches between a set of flights and a given set of flights of
interest:

```sql ST_TRACK_DWITHIN Example theme={null}
SELECT *
FROM TABLE
(
	ST_TRACK_DWITHIN
	(
		TRACK_TABLE => INPUT_TABLE(example_geospatial.flights),
		TRACK_ID_COLUMN => 'id',
		TRACK_X_COLUMN => 'lon',
		TRACK_Y_COLUMN => 'lat',
		TRACK_ORDER_COLUMN => 'flight_time',
		SEARCH_TABLE => INPUT_TABLE
						(
							SELECT id, lon, lat, flight_time
							FROM example_geospatial.flights_northwest
							UNION
							SELECT id, lon, lat, flight_time
							FROM example_geospatial.flights_northeast
						),
		SEARCH_ID_COLUMN => 1,
		SEARCH_X_COLUMN => 2,
		SEARCH_Y_COLUMN => 3,
		SEARCH_ORDER_COLUMN => 4,
		SEARCH_TIME_DISTANCE => '5m',
		SEARCH_XY_DISTANCE => '1km',
		SPATIAL_SOLUTION_TYPE => 1
	)
)
```

## ST\_TRACKINTERSECTS

The `ST_TRACKINTERSECTS` table function finds tracks pass through the given
geofence(s).  The geofence(s) use as the filter will be specified by the
`GEOFENCE_*` parameters.  The `TRACK_*` parameters specify the set of
tracks to search through for any intersecting the geofence(s).

The result will include a record for each intersecting track & geofence pair,
with:

* a `LINESTRING` representing the full track intersecting a geofence
* a `LINESTRING` representing the geofence it intersected

<Info>
  This function is only available in SQL or in the native API via
  [/execute/sql](/content/api/rest/execute_sql_rest).
</Info>

The basic form of the `ST_TRACKINTERSECTS` function follows.

```sql ST_TRACKINTERSECTS Table Function Syntax theme={null}
SELECT *
FROM TABLE
(
    ST_TRACKINTERSECTS
    (
        TRACK_TABLE => INPUT_TABLE(<table name | select statement>),
        TRACK_ID_COLUMN => < '<column name>' | <column position> >,
        TRACK_X_COLUMN => < '<column name>' | <column position> >,
        TRACK_Y_COLUMN => < '<column name>' | <column position> >,
        TRACK_ORDER_COLUMN => < '<column name>' | <column position> >,
        GEOFENCE_TABLE => INPUT_TABLE(<table name | select statement>),
        GEOFENCE_ID_COLUMN => < '<column name>' | <column position> >,
        GEOFENCE_WKT_COLUMN => < '<column name>' | <column position> >
    )
)
```

<AccordionGroup>
  <Accordion title="TRACK_TABLE" id="track_table-2" defaultOpen>
    Name of the table to search for tracks intersecting the geofence(s) specified in the `SEARCH_*` data
    set.

    To perform a search on the *flights* table, pass the name of the table to `INPUT_TABLE`:

    ```
    INPUT_TABLE(flights)
    ```

    To perform a search on the result of a query, pass the query to `INPUT_TABLE`:

    ```
    INPUT_TABLE
    (
        SELECT * FROM flights_west
        UNION
        SELECT * FROM flights_east
    )
    ```
  </Accordion>

  <Accordion title="TRACK_ID_COLUMN" id="track_id_column-2" defaultOpen>
    Table to search track column, containing the unique identifier for the track to which each track point
    belongs.
  </Accordion>

  <Accordion title="TRACK_X_COLUMN" id="track_x_column-2" defaultOpen>
    Table to search track column, containing the longitude value of each track point.
  </Accordion>

  <Accordion title="TRACK_Y_COLUMN" id="track_y_column-2" defaultOpen>
    Table to search track column, containing the latitude value of each track point.
  </Accordion>

  <Accordion title="TRACK_ORDER_COLUMN" id="track_order_column-2" defaultOpen>
    Table to search track column, by which the searched track points will be sorted in ascending order.
  </Accordion>

  <Accordion title="GEOFENCE_TABLE" id="geofence_table" defaultOpen>
    Name of the geofence table, containing the WKT(s) to be used as the filter criteria when searching for
    intersecting tracks in the `TRACK_*` data set.

    To search for tracks intersecting the geofence(s) from the *flight\_area\_of\_interest* table, pass the
    name of the geofence table to `INPUT_TABLE`:

    ```
    INPUT_TABLE(flight_area_of_interest)
    ```

    To search for tracks intersecting the geofence(s) from the result of a query, pass the query to
    `INPUT_TABLE`:

    ```
    INPUT_TABLE
    (
        SELECT * FROM flight_area_of_interest_west
        UNION
        SELECT * FROM flight_area_of_interest_east
    )
    ```
  </Accordion>

  <Accordion title="GEOFENCE_ID_COLUMN" id="geofence_id_column" defaultOpen>
    Geofence column, containing the unique identifier for the geofence.
  </Accordion>

  <Accordion title="GEOFENCE_WKT_COLUMN" id="geofence_wkt_column" defaultOpen>
    Geofence column, containing the WKT bounds of the geofence.
  </Accordion>
</AccordionGroup>

To see the intersections between a set of flights and an area of interest:

```sql ST_TRACKINTERSECTS Example theme={null}
SELECT *
FROM TABLE
(
	ST_TRACKINTERSECTS
	(
		TRACK_TABLE =>         INPUT_TABLE(example_geospatial.flights),
		TRACK_ID_COLUMN =>     'id',
		TRACK_X_COLUMN =>      'lon',
		TRACK_Y_COLUMN =>      'lat',
		TRACK_ORDER_COLUMN =>  'flight_time',
		GEOFENCE_TABLE =>      INPUT_TABLE(example_geospatial.track_geofence),
		GEOFENCE_ID_COLUMN =>  'fence_name',
		GEOFENCE_WKT_COLUMN => 'fence_wkt'
	)
)
ORDER BY id, fence_name
```