DocsICP FilingConsole
官方文档
首页

ST_{2D|2DT|3D|3DT}DWithin

更新时间：
复制 MD 格式
我的收藏

Returns true if the distance between two spatiotemporal objects on a specified axis is less than or equal to the specified threshold.

The function family has four variants based on the dimensional comparison mode:

  • 2D / 3D — compare objects based on their 2D or 3D spatial projections, independent of time.

  • 2DT / 3DT — compare objects at the same instant in time.

Syntax

bool ST_{2D|3D}DWithin(geometry geom, trajectory traj, float8 dist);
bool ST_{2D|3D}DWithin(trajectory traj, geometry geom, float8 dist);
bool ST_{2D|3D}DWithin(geometry geom, trajectory traj, timestamp ts, timestamp te, float8 dist);
bool ST_{2D|3D}DWithin(trajectory traj, geometry geom, timestamp ts, timestamp te, float8 dist);
bool ST_{2D|2DT|3D|3DT}DWithin(boxndf box, trajectory traj, float8 dist);
bool ST_{2D|2DT|3D|3DT}DWithin(trajectory traj, boxndf box, float8 dist);
bool ST_{2D|2DT|3D|3DT}DWithin(boxndf box, trajectory traj, timestamp ts, timestamp te, float8 dist);
bool ST_{2D|2DT|3D|3DT}DWithin(trajectory traj, boxndf box, timestamp ts, timestamp te, float8 dist);
bool ST_{2D|2DT|3D|3DT}DWithin(trajectory traj1, trajectory traj2, float8 dist);
bool ST_{2D|2DT|3D|3DT}DWithin(trajectory traj1, trajectory traj2, timestamp ts, timestamp te, float8 dist);

Parameters

ParameterDescription
geomThe geometry to compare.
trajThe trajectory to compare, or the original trajectory from which a sub-trajectory is extracted.
traj1The trajectory to compare, or the original trajectory from which a sub-trajectory is extracted.
traj2The trajectory to compare, or the original trajectory from which a sub-trajectory is extracted.
boxThe bounding box to compare.
tsThe start of the time range for sub-trajectory extraction. Optional.
teThe end of the time range for sub-trajectory extraction. Optional.
distThe threshold for the distance between the two objects.

How it works

2D and 3D variants measure the Euclidean distance between the 2D or 3D projections of two objects. The time dimension is ignored—only spatial position matters.

2DT and 3DT variants measure whether the distance between two objects in a specified dimension at a specified point in time falls within the threshold.

Time range (`ts` / `te`):

  • When ts and te are provided, the function operates on sub-trajectories within the [ts, te] interval.

  • When omitted, the function operates on complete trajectories.

Alias: ST_DistanceWithin is equivalent to ST_2DDWithin when one argument is a geometry, and equivalent to ST_3DTDWithin when both arguments are trajectories.

Example

The following example creates two trajectories and checks whether their distance is within the threshold across different time ranges and distance values. All calls use the sub-trajectory form with explicit ts and te parameters.

WITH traj AS (
    SELECT ST_makeTrajectory('STPOINT', 'LINESTRING(0 0 10, 50 0 10, 100 0 10)'::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"}]}') a,
           ST_makeTrajectory('STPOINT', 'LINESTRING(0 20, 50 20, 100 20)'::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
)
SELECT ST_2dDWithin(a, b, ST_PGEpochToTS(0), ST_PGEpochToTS(49), 19),  ST_3dDWithin(a, b, ST_PGEpochToTS(0), ST_PGEpochToTS(49), 19),
       ST_2dDWithin(a, b, ST_PGEpochToTS(0), ST_PGEpochToTS(50), 20),  ST_3dDWithin(a, b, ST_PGEpochToTS(0), ST_PGEpochToTS(50), 20),
       ST_2dDWithin(a, b, ST_PGEpochToTS(0), ST_PGEpochToTS(70), 21),  ST_3dDWithin(a, b, ST_PGEpochToTS(0), ST_PGEpochToTS(70), 21),
       ST_2dtDWithin(a, b, ST_PGEpochToTS(0), ST_PGEpochToTS(49), 19), ST_3dtDWithin(a, b, ST_PGEpochToTS(0), ST_PGEpochToTS(49), 19),
       ST_2dtDWithin(a, b, ST_PGEpochToTS(0), ST_PGEpochToTS(50), 20), ST_3dtDWithin(a, b, ST_PGEpochToTS(0), ST_PGEpochToTS(50), 20),
       ST_2dtDWithin(a, b, ST_PGEpochToTS(0), ST_PGEpochToTS(70), 21), ST_3dtDWithin(a, b, ST_PGEpochToTS(0), ST_PGEpochToTS(70), 21)
FROM traj;

Trajectory a runs along LINESTRING(0 0 10, 50 0 10, 100 0 10) and trajectory b along LINESTRING(0 20, 50 20, 100 20). Both span the same time range. The 2D distance between the two paths is exactly 20 (the y-axis offset).

NOTICE:  One or both of the geometries is missing z-value. The unknown z-value will be regarded as "any value"
NOTICE:  One or both of the geometries is missing z-value. The unknown z-value will be regarded as "any value"
 st_2ddwithin | st_3ddwithin | st_2ddwithin | st_3ddwithin | st_2ddwithin | st_3ddwithin | st_2dtdwithin | st_3dtdwithin | st_2dtdwithin | st_3dtdwithin | st_2dtdwithin | st_3dtdwithin
--------------+--------------+--------------+--------------+--------------+--------------+---------------+---------------+---------------+---------------+---------------+---------------
 f            | f            | t            | t            | t            | t            | f             | f             | t             | t             | t             | t

The results follow the same pattern for both 2D and 3D variants because trajectory b has no z-value (treated as "any value"). Key observations:

  • Threshold 19, time range [0, 49): Both 2D and 3D return f. The distance of 20 exceeds the threshold.

  • Threshold 20, time range [0, 50): Both return t. The distance equals the threshold (<= is inclusive).

  • Threshold 21, time range [0, 70): Both return t. The threshold comfortably covers the distance.

Previous：ST_{2D|2DT|3D|3DT}Intersects_IndexLeftNext：ST_{2D|2DT|3D|3DT}DWithin_IndexLeft