SDO_GEOM.SDO_DISTANCE

Format

SDO_GEOM.SDO_DISTANCE(
  geom1 IN SDO_GEOMETRY,
  dim1  IN SDO_DIM_ARRAY,
  geom2 IN SDO_GEOMETRY,
  dim2  IN SDO_DIM_ARRAY
  [, unit        IN VARCHAR2]
  [, ellipsoidal IN VARCHAR2]
) RETURN NUMBER;

or

SDO_GEOM.SDO_DISTANCE(
  geom1 IN SDO_GEOMETRY,
  geom2 IN SDO_GEOMETRY,
  tol   IN NUMBER
  [, unit        IN VARCHAR2]
  [, ellipsoidal IN VARCHAR2]
) RETURN NUMBER;

or

SDO_GEOM.SDO_DISTANCE(
  x1 IN NUMBER,
  y1 IN NUMBER,
  x2 IN NUMBER,
  y2 IN NUMBER
  [, srid IN NUMBER]
) RETURN NUMBER;

or

SDO_GEOM.SDO_DISTANCE(
  x1 IN NUMBER,
  y1 IN NUMBER,
  z1 IN NUMBER,
  x2 IN NUMBER
  y2 IN NUMBER,
  z2 IN NUMBER
  [, srid IN NUMBER]
) RETURN NUMBER;

Description

Computes the minimum distance between two geometry objects, which is the distance between the closest pair of points or segments of the two objects.

Parameters

geom1

Geometry object whose distance from geom2 is to be computed.

dim1

Dimensional information array corresponding to geom1, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Geometry Metadata Views).

geom2

Geometry object whose distance from geom1 is to be computed.

dim2

Dimensional information array corresponding to geom2, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Geometry Metadata Views).

unit

Unit of measurement: a quoted string with unit= and an SDO_UNIT value from the MDSYS.SDO_DIST_UNITS table (for example, ‘unit=KM’). See Unit of Measurement Support for more information about unit of measurement specification.

If this parameter is not specified, the unit of measurement associated with the data is assumed.

ellipsoidal

Specifies if ellipsoidal distance is always used with geodetic data (true), or if spherical distance is used in some cases (false, the default). See Distance: Spherical versus Ellipsoidal with Geodetic Data.

tol

Tolerance value (see Tolerance).

x1

X-coordinate of the first point.

y1

Y-coordinate of the first point.

z1

Z-coordinate of the first point.

x2

X-coordinate of the second point.

y2

Y-coordinate of the second point.

z2

Z-coordinate of the second point.

srid

SRID coordinate system used for the point cloud.

Usage Notes

An exception is raised if geom1 and geom2 are based on different coordinate systems.

Overloaded forms of this function accept the 2D (x1, y1, x2, y2) or 3D (x1, y1, z1, x2, y2, z2) coordinate values of two points and compute the distance directly, avoiding the overhead of creating SDO_GEOMETRY objects.

If the input data is three-dimensional and geodetic, a 3D SRID must be used for the geometries; otherwise, the results will be incorrect.

Examples

The following example returns the shortest distance between cola_b and cola_d. (The example uses the definitions and data from Simple Example: Inserting_ Indexing_ and Querying Spatial Data.)

-- Return the distance between two geometries.
SELECT SDO_GEOM.SDO_DISTANCE(c_b.shape, c_d.shape, 0.005)
   FROM cola_markets c_b, cola_markets c_d
   WHERE c_b.name = 'cola_b' AND c_d.name = 'cola_d';

SDO_GEOM.SDO_DISTANCE(C_B.SHAPE,C_D.SHAPE,0.005)
------------------------------------------------
                                      .846049894