Checks whether the first object is fully contained within the second object on the specified dimension(s). Returns true if the first object lies entirely inside the second; otherwise returns false. This function works in the same way as the ST_ndContains function.
Syntax
bool ST_TWithin(tsrange r, trajectory traj);
bool ST_TWithin(trajectory traj, tsrange r);
bool ST_2DWithin(geometry geom, trajectory traj);
bool ST_2DWithin(trajectory traj, geometry geom);
bool ST_2DWithin(geometry geom, trajectory traj, timestamp ts, timestamp te);
bool ST_2DWithin(trajectory traj, geometry geom, timestamp ts, timestamp te);
bool ST_{2D|2DT|3D|3DT}Within(trajectory traj, boxndf box);
bool ST_{2D|2DT|3D|3DT}Within(trajectory traj, boxndf box, timestamp ts, timestamp te);Variant overview
Each variant checks containment on a different set of dimensions. Use this table to select the right function for your query.
| Function | Containment check | Accepts time range? |
|---|---|---|
ST_TWithin | Time axis only | Yes (tsrange) |
ST_2DWithin | 2D space (X, Y) | Yes (optional ts/te) |
ST_2DTWithin | 2D space + time | Yes (optional ts/te) |
ST_3DWithin | 3D space (X, Y, Z) | Yes (optional ts/te) |
ST_3DTWithin | 3D space + time | Yes (optional ts/te) |
Parameters
| Parameter | Description |
|---|---|
geom | The geometry to compare. |
traj | The trajectory to compare, or the original trajectory that contains the sub-trajectory to compare. |
box | The bounding box (boxndf) to compare. |
r | The time range (tsrange) to compare. |
ts | Start of the time range for sub-trajectory extraction. Optional. |
te | End of the time range for sub-trajectory extraction. Optional. |
Usage notes
ST_{T|2D|2DT|3D|3DT}Withinworks in the same way asST_ndContains.When
tsandteare provided, the function extracts the sub-trajectory within that time range before checking containment.Not supported for geometry types such as
POLYHEDRALSURFACE.
Example
The following example checks whether a geometry (b) is fully contained within a trajectory (a) on the 2D spatial axes. Both a and b share the same LINESTRING coordinates, so the result is true.
WITH traj AS(
SELECT (' {"trajectory":{"version":1,"type":"STPOINT","leafcount":6,"start_time":"2000-01-01 03:15:42","end_time":"2000-01-01 05:16:43",' ||
'"spatial":"LINESTRING(2 2 0,33.042158099636 36.832684322819 0,47.244002354518 47.230026333034 0,64.978971942887 60.618813472986 0,77.621717839502 78.012496630661 0,80 78 0)",' ||
'"timeline":["2000-01-01 03:15:42","2000-01-01 03:39:54","2000-01-01 04:04:06","2000-01-01 04:28:18","2000-01-01 04:52:31","2000-01-01 05:16:43"]}}')::trajectory a,
'LINESTRING(2 2 0,33.042158099636 36.832684322819 0,47.244002354518 47.230026333034 0,64.978971942887 60.618813472986 0,77.621717839502 78.012496630661 0,80 78 0)'::geometry b
)
SELECT ST_2dWithin(b,a) from traj;
st_2dwithin
-------------
t