Add support for Filter Extension s_intersects operator (#854)

* add support for Filter Extension s_intersects

Author: Phil Varner

CHANGELOG.md

@@ -9,7 +9,11 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ### Added
 
-- Added support for the "in" and "between" operators of the Filter Extension
+- Support for the "in" and "between" operators of the Filter Extension
+- Support for "s_intersects" opeartor of the Filter Extension. This implements both the
+  "Basic Spatial Functions" and "Basic Spatial Functions with additional Spatial Literals"
+  conformance classes, supporting operands for s_intersects of either bbox or GeoJSON
+  Geometry literals.
 
 ## [3.10.0] - 2025-03-21
 

src/lib/api.js

@@ -1,11 +1,11 @@
 import { pickBy, assign, get as getNested } from 'lodash-es'
-import extent from '@mapbox/extent'
 import { DateTime } from 'luxon'
 import { getSignedUrl } from '@aws-sdk/s3-request-presigner'
 import { S3Client, GetObjectCommand } from '@aws-sdk/client-s3'
 import { ValidationError } from './errors.js'
 import { isIndexNotFoundError } from './database.js'
 import logger from './logger.js'
+import { bboxToPolygon } from './geo-utils.js'
 
 // max number of collections to retrieve
 const COLLECTION_LIMIT = process.env['STAC_SERVER_COLLECTION_LIMIT'] || 100
@@ -79,32 +79,7 @@ export const extractIntersects = function (params) {
 
 export const extractBbox = function (params, httpMethod = 'GET') {
   const { bbox } = params
-  if (bbox) {
-    let bboxArray
-    if (httpMethod === 'GET' && typeof bbox === 'string') {
-      try {
-        bboxArray = bbox.split(',').map(parseFloat).filter((x) => !Number.isNaN(x))
-      } catch (_) {
-        throw new ValidationError('Invalid bbox')
-      }
-    } else if (httpMethod === 'POST' && Array.isArray(bbox)) {
-      bboxArray = bbox
-    } else {
-      throw new ValidationError('Invalid bbox')
-    }
-
-    if (bboxArray.length !== 4 && bboxArray.length !== 6) {
-      throw new ValidationError('Invalid bbox, must have 4 or 6 points')
-    }
-
-    if ((bboxArray.length === 4 && bboxArray[1] > bboxArray[3])
-        || (bboxArray.length === 6 && bboxArray[1] > bboxArray[4])) {
-      throw new ValidationError('Invalid bbox, SW latitude must be less than NE latitude')
-    }
-
-    return extent(bboxArray).polygon()
-  }
-  return undefined
+  return bboxToPolygon(bbox, httpMethod === 'GET')
 }
 
 export const extractLimit = function (params) {
@@ -984,6 +959,8 @@ const getConformance = async function (txnEnabled) {
     'http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/features-filter',
     'http://www.opengis.net/spec/cql2/1.0/conf/basic-cql2',
     'http://www.opengis.net/spec/cql2/1.0/conf/cql2-json',
+    'http://www.opengis.net/spec/cql2/1.0/conf/basic-spatial-functions',
+    'http://www.opengis.net/spec/cql2/1.0/conf/basic-spatial-functions-plus',
   ]
 
   if (txnEnabled) {

src/lib/database.js

@@ -2,6 +2,7 @@ import { isEmpty } from 'lodash-es'
 import { dbClient as _client, createIndex } from './database-client.js'
 import logger from './logger.js'
 import { ValidationError } from './errors.js'
+import { bboxToPolygon } from './geo-utils.js'
 
 const COLLECTIONS_INDEX = process.env['COLLECTIONS_INDEX'] || 'collections'
 const DEFAULT_INDICES = ['*', '-.*', '-collections']
@@ -19,6 +20,7 @@ const OP = {
   IN: 'in',
   BETWEEN: 'between',
   LIKE: 'like',
+  S_INTERSECTS: 's_intersects',
 }
 const RANGE_TRANSLATION = {
   '<': 'lt',
@@ -32,6 +34,8 @@ const UNPREFIXED_FIELDS = [
   'geometry',
   'bbox'
 ]
+const GEOMETRY_TYPES = ['Point', 'LineString', 'Polygon', 'MultiPoint',
+  'MultiLineString', 'MultiPolygon', 'GeometryCollection']
 
 let collectionToIndexMapping = null
 let unrestrictedIndices = null
@@ -101,6 +105,84 @@ export function buildDatetimeQuery(parameters) {
   return dateQuery
 }
 
+function IN(cql2Field, cql2Value) {
+  if (!Array.isArray(cql2Value) || cql2Value.length === 0) {
+    throw new ValidationError("Operand for 'in' must be a non-empty array")
+  }
+  if (!cql2Value.every((x) => x !== Object(x))) {
+    throw new ValidationError(
+      "Operand for 'in' must contain only string, number, or boolean types"
+    )
+  }
+
+  return {
+    terms: {
+      [cql2Field]: cql2Value
+    }
+  }
+}
+
+function between(cql2Field, filterArgs) {
+  if (filterArgs.length < 3) {
+    throw new ValidationError("Two operands must be provided for the 'between' operator")
+  }
+
+  const cql2Value1 = filterArgs[1]
+  const cql2Value2 = filterArgs[2]
+  if (!(typeof cql2Value1 === 'number' && typeof cql2Value2 === 'number')) {
+    throw new ValidationError("Operands for 'between' must be numbers")
+  }
+
+  if (cql2Value1 > cql2Value2) {
+    throw new ValidationError(
+      "For the 'between' operator, the first operand must be less than or equal "
+        + 'to the second operand'
+    )
+  }
+
+  return {
+    range: {
+      [cql2Field]: {
+        gte: cql2Value1,
+        lte: cql2Value2
+      }
+    }
+  }
+}
+
+function sIntersects(cql2Field, cql2Value) {
+  // cql2Value can be either:
+  // 1) { "bbox": [swLon, swLat, neLon, neLat] }
+  // 2) geojson geometry
+
+  let geom = null
+
+  if (cql2Value.bbox) {
+    geom = bboxToPolygon(cql2Value.bbox, true)
+  }
+
+  if (cql2Value.type && cql2Value.coordinates) {
+    if (!GEOMETRY_TYPES.includes(cql2Value.type)) {
+      throw new ValidationError(
+        `Operand for 's_intersects' must be a GeoJSON geometry: type was '${cql2Value.type}'`
+      )
+    }
+    geom = cql2Value
+  }
+
+  if (!geom) {
+    throw new ValidationError(
+      "Operand for 's_intersects' must be a bbox literal or GeoJSON geometry"
+    )
+  }
+
+  return {
+    geo_shape: {
+      [cql2Field]: { shape: geom }
+    }
+  }
+}
+
 function buildQueryExtQuery(query) {
   const eq = 'eq'
   const inop = 'in'
@@ -280,49 +362,13 @@ function buildFilterExtQuery(filter) {
       }
     }
   case OP.IN:
-    if (!Array.isArray(cql2Value) || cql2Value.length === 0) {
-      throw new ValidationError("Operand for 'in' must be a non-empty array")
-    }
-    if (!cql2Value.every((x) => x !== Object(x))) {
-      throw new ValidationError(
-        "Operand for 'in' must contain only string, number, or boolean types"
-      )
-    }
-
-    return {
-      terms: {
-        [cql2Field]: cql2Value
-      }
-    }
+    return IN(cql2Field, cql2Value)
   case OP.BETWEEN:
-    if (filter.args.length < 3) {
-      throw new ValidationError("Two operands must be provided for the 'between' operator")
-    }
-
-    // eslint-disable-next-line no-case-declarations
-    const cql2Value2 = filter.args[2]
-    if (!(typeof cql2Value === 'number' && typeof cql2Value2 === 'number')) {
-      throw new ValidationError("Operands for 'between' must be numbers")
-    }
-
-    if (cql2Value > cql2Value2) {
-      throw new ValidationError(
-        "For the 'between' operator, the first operand must be less than or equal "
-        + 'to the second operand'
-      )
-    }
-
-    return {
-      range: {
-        [cql2Field]: {
-          gte: cql2Value,
-          lte: cql2Value2
-        }
-      }
-    }
-
+    return between(cql2Field, filter.args)
   case OP.LIKE:
     throw new ValidationError("The 'like' operator is not currently supported")
+  case OP.S_INTERSECTS:
+    return sIntersects(cql2Field, cql2Value)
 
   // should not get here
   default:

src/lib/geo-utils.js

@@ -0,0 +1,35 @@
+import extent from '@mapbox/extent'
+import { ValidationError } from './errors.js'
+
+// eslint-disable-next-line import/prefer-default-export
+export const bboxToPolygon = function (bbox, fromString) {
+  if (bbox) {
+    let bboxArray
+    if (fromString && typeof bbox === 'string') {
+      try {
+        bboxArray = bbox.split(',').map(parseFloat).filter((x) => !Number.isNaN(x))
+      } catch (_) {
+        throw new ValidationError('Invalid bbox')
+      }
+    } else {
+      bboxArray = bbox
+    }
+
+    if (!Array.isArray(bboxArray)) {
+      throw new ValidationError('Invalid bbox')
+    }
+
+    if (bboxArray.length !== 4 && bboxArray.length !== 6) {
+      throw new ValidationError('Invalid bbox, must have 4 or 6 points')
+    }
+
+    if ((bboxArray.length === 4 && bboxArray[1] > bboxArray[3])
+        || (bboxArray.length === 6 && bboxArray[1] > bboxArray[4])) {
+      throw new ValidationError('Invalid bbox, SW latitude must be less than NE latitude')
+    }
+
+    return extent(bboxArray).polygon()
+  }
+
+  return undefined
+}

tests/system/test-api-get-conformance.js

@@ -13,7 +13,7 @@ test.after.always(async (t) => {
 
 test('GET /conformance returns the expected conformsTo list', async (t) => {
   const response = await t.context.api.client.get('conformance')
-  t.is(response.conformsTo.length, 22)
+  t.is(response.conformsTo.length, 24)
 })
 
 test('GET /conformance has a content type of "application/json', async (t) => {

tests/system/test-api-search-post.js

@@ -13,6 +13,7 @@ import { loadJson, setup } from '../helpers/system-tests.js'
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename) // eslint-disable-line no-unused-vars
 const intersectsGeometry = fs.readFileSync(path.resolve(__dirname, '../fixtures/stac/intersectsGeometry.json'), 'utf8')
+const noIntersectsGeometry = fs.readFileSync(path.resolve(__dirname, '../fixtures/stac/noIntersectsGeometry.json'), 'utf8')
 
 const fixture = (filepath) => fs.readFileSync(path.resolve(__dirname, filepath), 'utf8')
 
@@ -1290,3 +1291,71 @@ test('/search - filter extension - BETWEEN - failure for number args reversed',
     // eslint-disable-next-line max-len
     /.*For the 'between' operator, the first operand must be less than or equal to the second operand*/)
 })
+
+test('/search - filter extension - s_intersects - no matches for bbox', async (t) => {
+  const response = await t.context.api.client.post('search', {
+    json: {
+      filter: {
+        op: 's_intersects',
+        args: [{ property: 'geometry' }, { bbox: [-1, -1, 0, 0] }]
+      }
+    }
+  })
+  t.is(response.features.length, 0)
+})
+
+test('/search - filter extension - s_intersects - no matches for polygon', async (t) => {
+  const response = await t.context.api.client.post('search', {
+    json: {
+      filter: {
+        op: 's_intersects',
+        args: [{ property: 'geometry' }, JSON.parse(noIntersectsGeometry)]
+      }
+    }
+  })
+  t.is(response.features.length, 0)
+})
+
+test('/search - filter extension - s_intersects - matches for polygon', async (t) => {
+  const response = await t.context.api.client.post('search', {
+    json: {
+      filter: {
+        op: 's_intersects',
+        args: [{ property: 'geometry' }, JSON.parse(intersectsGeometry)]
+      }
+    }
+  })
+  t.is(response.features.length, 3)
+})
+
+test('/search - filter extension - s_intersects - failure for not bbox or geometry', async (t) => {
+  const error = await t.throwsAsync(async () => t.context.api.client.post('search', {
+    json: {
+      filter: {
+        op: 's_intersects',
+        args: [{ property: 'geometry' }, { not_bbox: 'foo' }]
+      }
+    }
+  }))
+  t.is(error.response.statusCode, 400)
+  t.is(error.response.body.code, 'BadRequest')
+  t.regex(error.response.body.description,
+    // eslint-disable-next-line max-len
+    /.*Operand for 's_intersects' must be a bbox literal or GeoJSON geometry*/)
+})
+
+test('/search - filter extension - s_intersects - non-existent geometry type', async (t) => {
+  const error = await t.throwsAsync(async () => t.context.api.client.post('search', {
+    json: {
+      filter: {
+        op: 's_intersects',
+        args: [{ property: 'geometry' }, { type: 'notPolygon', coordinates: [] }]
+      }
+    }
+  }))
+  t.is(error.response.statusCode, 400)
+  t.is(error.response.body.code, 'BadRequest')
+  t.regex(error.response.body.description,
+    // eslint-disable-next-line max-len
+    /.*Operand for 's_intersects' must be a GeoJSON geometry: type was 'notPolygon'*/)
+})