PolarDB:ST_{T|2D|2DT|3D|3DT}Contains

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);

Parameters

Description

The function family covers two comparison modes depending on the type of the first argument.

Geometry mode (ST_2DContains with a geometry argument): Compares the two-dimensional projections of complete trajectories or sub-trajectories over a specified time range, then checks whether the geometry contains or is contained in the other object.

Bounding box mode (ST_{2D|2DT|3D|3DT}Contains with a boxndf argument): Checks whether the trajectory, or its sub-trajectory over a specified time range, falls inside the bounding box across all specified dimensions. If the bounding box, trajectory, or sub-trajectory lacks a given dimension, that dimension is treated as unbounded and automatically satisfies the containment condition.

The five variants differ in which dimensions they evaluate:

POLYHEDRALSURFACE geometry types are not supported.

Example

The following example creates a trajectory and a 3D bounding box, then evaluates containment across three time ranges using all four multi-dimensional variants (ST_2DContains, ST_3DContains, ST_2DTContains, ST_3DTContains).

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"}]}') b,
           ST_MakeBox3dt(0,0,0,ST_PgEpochToTS(0), 50,50,50, ST_PgEpochToTS(49)) a
)
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)),
       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)),
       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 | st_2dcontains | st_3dcontains | st_2dtcontains | st_3dtcontains | st_2dcontains | st_3dcontains | st_2dtcontains | st_3dtcontains
---------------+---------------+----------------+----------------+---------------+---------------+----------------+----------------+---------------+---------------+----------------+----------------
 t             | t             | t              | t              | t             | t             | f              | f              | f             | f             | f              | f

The bounding box spans coordinates (0,0,0) to (50,50,50) in XYZ space and timestamps 0 to 49. The results differ across time ranges:

• ts=0, te=49: The sub-trajectory from timestamp 0 to 49 stays within the box in all dimensions — all four variants return t.

• ts=0, te=50: At timestamp 50, the trajectory point reaches (50,50,50) with timestamp 50, which falls outside the temporal bound of the box (max timestamp = 49). Spatial variants (ST_2DContains, ST_3DContains) still return t because they ignore the time dimension; temporal variants (ST_2DTContains, ST_3DTContains) return f because the timestamp 50 exceeds the box boundary.

• ts=0, te=70: The sub-trajectory extends to point (70,70,70), which falls outside the spatial bound (max coordinate = 50). All four variants return f.