SDO_GEOM.RELATE

Format

SDO_GEOM.RELATE(     
  geom1  IN SDO_GEOMETRY,      
  dim1   IN SDO_DIM_ARRAY,      
  mask   IN VARCHAR2,      
  geom2  IN SDO_GEOMETRY,      
  dim2   IN SDO_DIM_ARRAY       
) RETURN VARCHAR2;

or

SDO_GEOM.RELATE(     
  geom1  IN SDO_GEOMETRY,      
  mask   IN VARCHAR2,      
  geom2  IN SDO_GEOMETRY,      
  tol    IN NUMBER       
) RETURN VARCHAR2;

Description

Examines two geometry objects to determine their spatial relationship.

Parameters

geom1: Geometry object.
dim1: Dimensional information array corresponding to geom1, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Geometry Metadata Views).
mask: Specifies a list of relationships to check. See the list of keywords in the Usage Notes.
geom2: Geometry object.
dim2: Dimensional information array corresponding to geom2, usually selected from one of the xxx_SDO_GEOM_METADATA views (described in Geometry Metadata Views).
tol: Tolerance value (see Tolerance).

Usage Notes

For better performance, use the SDO_RELATE operator or one of its convenience operator formats (all described in Spatial Operators ) instead of the SDO_GEOM.RELATE function, unless you need to use the function. For example, the DETERMINE mask keyword does not apply with the SDO_RELATE operator. For more information about performance considerations with operators and functions, see Spatial Operators_ Procedures_ and Functions.

The SDO_GEOM.RELATE function can return the following types of answers:

If you pass a mask listing one or more relationships, the function returns the specified mask value if one or more of the relationships are true for the pair of geometries. If all relationships are false, the procedure returns FALSE.
If you pass the DETERMINE keyword in mask, the function returns the one relationship keyword that best matches the geometries.
If you pass the ANYINTERACT keyword in mask, the function returns TRUE if the two geometries are not disjoint.

The following mask relationships can be tested:

ANYINTERACT: Returns TRUE if the objects are not disjoint.
CONTAINS: Returns CONTAINS if the second object is entirely within the first object and the object boundaries do not touch; otherwise, returns FALSE.
COVEREDBY: Returns COVEREDBY if the first object is entirely within the second object and the object boundaries touch at one or more points; otherwise, returns FALSE.
COVERS: Returns COVERS if the second object is entirely within the first object and the boundaries touch in one or more places; otherwise, returns FALSE.
DISJOINT: Returns DISJOINT if the objects have no common boundary or interior points; otherwise, returns FALSE.
EQUAL: Returns EQUAL if the boundaries and interior of the objects exactly overlap, including any holes (that is, if the two geometries are topologically equal); otherwise, returns FALSE.
INSIDE: Returns INSIDE if the first object is entirely within the second object and the object boundaries do not touch; otherwise, returns FALSE.
ON: Returns ON if the boundary and interior of a line (the first object) is completely on the boundary of a polygon (the second object); otherwise, returns FALSE.
OVERLAPBDYDISJOINT: Returns OVERLAPBDYDISJOINT if the objects overlap, but their boundaries do not interact; otherwise, returns FALSE.
OVERLAPBDYINTERSECT: Returns OVERLAPBDYINTERSECT if the objects overlap, and their boundaries intersect in one or more places; otherwise, returns FALSE.
TOUCH: Returns TOUCH if the two objects share a common boundary point, but no interior points; otherwise, returns FALSE.

Values for mask can be combined using the logical Boolean operator OR. For example, 'INSIDE + TOUCH' returns INSIDE+TOUCH if the relationship between the geometries is INSIDE or TOUCH or both INSIDE and TOUCH; it returns FALSE if the relationship between the geometries is neither INSIDE nor TOUCH.

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

Examples

The following example finds the relationship between each geometry in the SHAPE column and the cola_b geometry. (The example uses the definitions and data from Simple Example: Inserting_ Indexing_ and Querying Spatial Data. The output is reformatted for readability.)

SELECT c.name,
  SDO_GEOM.RELATE(c.shape, 'determine', c_b.shape, 0.005) relationship 
  FROM cola_markets c, cola_markets c_b WHERE c_b.name = 'cola_b';

NAME     RELATIONSHIP 
---------------------------                                  cola_a   TOUCH
cola_b   EQUAL
cola_c   OVERLAPBDYINTERSECT
cola_d   DISJOINT