Overview of Filter Spatial Operators

You can use filter operator $near, $intersects, or $within to select documents that have a field whose value is a GeoJSON geometry object that is near a specified position, intersectsa specified geometric object, or is withinanother specified geometric object, respectively.

Note: To use filter spatial operators you need Oracle Database Release 12c (12.2.0.1) or later.

The following filter selects only documents that have a location field whose value is a Point GeoJSON geometry object that represents a position within 50 kilometers of the coordinates [34.0162, -118.2019].

{ "location" :
  { "$near" :
    { "$geometry" : { "type" : "Point",
                      "coordinates" : [34.0162, -118.2019] },
      "$distance" : 50,
      "$unit"     : "KM" } } }

It can retrieve a document that has an object such as this one, for example:

{ "location" : { "type" : "Point",
                 "coordinates": [33.7243, -118.1579] } }

Any document that does not contain a location field is ignored (skipped) without error. But if the queried collection contains a document with a location field that does not have as value a (single) GeoJSON geometry object then an error is raised. A document with this object, for example, raises an error:

{ "location" : "1600 Pennsylvania Ave NW, Washington, DC 20500" }

You can provide different (non-default) error-handling behavior for your filter by including a true-valued $scalarRequired or $lax field (but not both together) in the object that is the value of spatial operator $near, $intersects, or $within.

For example, this fitler raises an error if any document has no location field or if any document has a location field whose value is not a geometry object:

{ "location" :
  { "$near" :
    { "$geometry"      : { "type" : "Point",
                           "coordinates" : [34.0162, -118.2019] },
      "$distance"      : 50,
      "$unit"          : "KM",
      "$scalarRequired : true** } } }

And this filter does not raise an error for a document that has no location field or for a document that has a location field whose value is not a geometry object:

{ "location" :
  { "$near" :
    { "$geometry" : { "type" : "Point",
                      "coordinates" : [34.0162, -118.2019] },
      "$distance" : 50,
      "$unit"     : "KM",
      "$lax"      : true } } }

Note:

If you have created a SODA spatial index for a field whose value is a GeoJSON geometry object, and if you use a filter that targets that field, then the index can be picked up for the filter only if both index and filter specify the same error-handling behavior for that field. Both must specify the same one of these:

Related Topics