Use ST_{T|2D|2DT|3D|3DT}Contains to judge spatio-temporal inclusion relationships - ApsaraDB RDS

Returns true if the first argument contains the second argument on the specified axis.

Syntax

bool ST_TContains(tsrange r, trajectory traj);
bool ST_TContains(trajectory traj, tsrange r);
bool ST_2DContains(geometry geom, trajectory traj);
bool ST_2DContains(trajectory traj, geometry geom);
bool ST_2DContains(geometry geom, trajectory traj, timestamp ts, timestamp te);
bool ST_2DContains(trajectory traj, geometry geom, timestamp ts, timestamp te);
bool ST_{2D|2DT|3D|3DT}Contains(boxndf box, trajectory traj);
bool ST_{2D|2DT|3D|3DT}Contains(boxndf box, trajectory traj, timestamp ts, timestamp te);

Variants

Each function variant checks containment on a different set of axes:

Variant	Axes checked	First argument	Second argument
`ST_TContains`	Time (T)	`tsrange` or `trajectory`	`trajectory` or `tsrange`
`ST_2DContains`	2D space (X, Y)	`geometry` or `trajectory`	`trajectory` or `geometry`
`ST_2DTContains`	2D space + time (X, Y, T)	`boxndf`	`trajectory`
`ST_3DContains`	3D space (X, Y, Z)	`boxndf`	`trajectory`
`ST_3DTContains`	3D space + time (X, Y, Z, T)	`boxndf`	`trajectory`

Parameters

Parameter	Description
`geom`	The geometry to compare.
`traj`	The trajectory to compare, or the source trajectory from which a sub-trajectory is extracted.
`box`	The bounding box to compare.
`r`	The time range to query.
`ts`	The start of the time range for sub-trajectory extraction. Optional.
`te`	The end of the time range for sub-trajectory extraction. Optional.

Description

ST_{T|2D|2DT|3D|3DT}Contains checks whether the first argument contains the second argument on the specified axis.

Time range variant (ST_TContains): Checks whether the time range or trajectory contains the other argument on the time axis.

Geometry variant (ST_2DContains): Compares the two-dimensional projections of complete trajectories or sub-trajectories over a specified time range. The function returns true if the geometry contains, or is contained by, the other argument.

Bounding box variants (ST_2DTContains, ST_3DContains, ST_3DTContains): Check whether a trajectory (or its sub-trajectory over a specified time range) falls entirely within the bounding box across all specified dimensions. If the bounding box, trajectory, or sub-trajectory lacks a given dimension, that dimension is treated as having any value and automatically satisfies the containment condition.

POLYHEDRALSURFACE and similar geometry types are not supported.

Examples

The following examples use a common CTE that creates a trajectory and a 3D bounding box, then test each variant across three time ranges.

Setup:

WITH traj AS (
    SELECT
        ST_makeTrajectory(
            'STPOINT',
            'LINESTRING(0 0, 50 50, 100 100)'::geometry,
            ('[' || ST_PGEpochToTS(0) || ',' || ST_PGEpochToTS(100) || ')')::tsrange,
            '{"leafcount":3,"attributes":{"velocity": {"type": "integer", "length": 2,"nullable" : true,"value": [120,130,140]}, "accuracy": {"type": "float", "length": 4, "nullable" : false,"value": [120,130,140]}, "bearing": {"type": "float", "length": 8, "nullable" : false,"value": [120,130,140]}, "acceleration": {"type": "string", "length": 20, "nullable" : true,"value": ["120","130","140"]}, "active": {"type": "timestamp", "nullable" : false,"value": ["Fri Jan 01 11:35:00 2010", "Fri Jan 01 12:35:00 2010", "Fri Jan 01 13:30:00 2010"]}}, "events": [{"2" : "Fri Jan 02 15:00:00 2010"}, {"3" : "Fri Jan 02 15:30:00 2010"}]}'
        ) AS b,
        ST_MakeBox3dt(0,0,0,ST_PgEpochToTS(0), 50,50,50,ST_PgEpochToTS(49)) AS a
)

The bounding box a covers coordinates [0–50, 0–50, 0–50] and time [0–49]. The trajectory b runs from (0,0) to (100,100) over time [0–100].

Time range [0, 49] — sub-trajectory stays within the box:

SELECT
    ST_2dContains(a, b, ST_PGEpochToTS(0), ST_PGEpochToTS(49)),
    ST_3dContains(a, b, ST_PGEpochToTS(0), ST_PGEpochToTS(49)),
    ST_2dtContains(a, b, ST_PGEpochToTS(0), ST_PGEpochToTS(49)),
    ST_3dtContains(a, b, ST_PGEpochToTS(0), ST_PGEpochToTS(49))
FROM traj;

st_2dcontains	st_3dcontains	st_2dtcontains	st_3dtcontains
t	t	t	t

All variants return true: the sub-trajectory from time 0 to 49 lies within the bounding box on all axes.

Time range [0, 50] — sub-trajectory reaches the box boundary on the time axis:

SELECT
    ST_2dContains(a, b, ST_PGEpochToTS(0), ST_PGEpochToTS(50)),
    ST_3dContains(a, b, ST_PGEpochToTS(0), ST_PGEpochToTS(50)),
    ST_2dtContains(a, b, ST_PGEpochToTS(0), ST_PGEpochToTS(50)),
    ST_3dtContains(a, b, ST_PGEpochToTS(0), ST_PGEpochToTS(50))
FROM traj;

st_2dcontains	st_3dcontains	st_2dtcontains	st_3dtcontains
t	t	f	f

ST_2DContains and ST_3DContains return true because they do not check the time axis — the spatial projection of the sub-trajectory still fits within the box. ST_2DTContains and ST_3DTContains return false because time 50 falls outside the box's time bound of 49.

Time range [0, 70] — sub-trajectory exceeds the box on both spatial and time axes:

SELECT
    ST_2dContains(a, b, ST_PGEpochToTS(0), ST_PGEpochToTS(70)),
    ST_3dContains(a, b, ST_PGEpochToTS(0), ST_PGEpochToTS(70)),
    ST_2dtContains(a, b, ST_PGEpochToTS(0), ST_PGEpochToTS(70)),
    ST_3dtContains(a, b, ST_PGEpochToTS(0), ST_PGEpochToTS(70))
FROM traj;

st_2dcontains	st_3dcontains	st_2dtcontains	st_3dtcontains
f	f	f	f

All variants return false: by time 70, the trajectory has moved to coordinates (70, 70), which exceed the box's spatial bound of 50.