{
  "name": "overlay_intersects",
  "type": "function",
  "groups": ["GeometryGroup"],
  "description": "Returns whether the current feature spatially intersects at least one feature from a target layer, or an array of expression-based results for the features in the target layer intersected by the current feature.<br><br>Read more on the underlying GEOS \"Intersects\" predicate, as described in PostGIS <a href='https://postgis.net/docs/ST_Intersects.html'>ST_Intersects</a> function.",
  "arguments": [
    {
      "arg": "layer",
      "description": "the layer whose overlay is checked"
    },
    {
      "arg": "expression",
      "description": "an optional expression to evaluate on the features from the target layer. If not set, the function will just return a boolean indicating whether there is at least one match.",
      "optional": true
    },
    {
      "arg": "filter",
      "description": "an optional expression to filter the target features to check. If not set, all the features will be checked.",
      "optional": true
    },
    {
      "arg": "limit",
      "description": "an optional integer to limit the number of matching features. If not set, all the matching features will be returned.",
      "optional": true
    },
    {
      "arg": "cache",
      "description": "set this to true to build a local spatial index (most of the time, this is unwanted, unless you are working with a particularly slow data provider)",
      "optional": true,
      "default": "false"
    },
    {
      "arg": "min_overlap",
      "description": "defines an optional exclusion filter:<ul><li>for polygons, a minimum area in current feature squared units for the intersection. If the intersection results in multiple polygons the intersection will be returned if at least one of the polygons has an area greater or equal to the value</li><li>for lines, a minimum length in current feature units. If the intersection results in multiple lines the intersection will be returned if at least one of the lines has a length greater or equal to the value.</li></ul>",
      "optional": true
    },
    {
      "arg": "min_inscribed_circle_radius",
      "description": "defines an optional exclusion filter (for polygons only): minimum radius in current feature units for the maximum inscribed circle of the intersection. If the intersection results in multiple polygons the intersection will be returned if at least one of the polygons has a radius for the maximum inscribed circle greater or equal to the value.<br>Read more on the underlying GEOS predicate, as described in PostGIS <a href='https://postgis.net/docs/ST_MaximumInscribedCircle.html'>ST_MaximumInscribedCircle</a> function.<br>This argument requires GEOS >= 3.9.",
      "optional": true
    },
    {
      "arg": "return_details",
      "description": "Set this to true to return a list of maps containing (key names in quotes) the feature 'id', the expression 'result' and the 'overlap' value (of the largest element in case of multipart). The 'radius' of the maximum inscribed circle is also returned when the target layer is a polygon. Only valid when used with the expression parameter",
      "optional": true
    },
    {
      "arg": "sort_by_intersection_size",
      "description": "only valid when used with an expression, set this to 'des' to return the results ordered by the overlap value in descending order or set this to 'asc' for ascending order.",
      "optional": true
    }
  ],
  "examples": [
    {
      "expression": "overlay_intersects('regions')",
      "returns": "TRUE if the current feature spatially intersects a region"
    },
    {
      "expression": "overlay_intersects('regions', filter:= population > 10000)",
      "returns": "TRUE if the current feature spatially intersects a region with a population greater than 10000"
    },
    {
      "expression": "overlay_intersects('regions', name)",
      "returns": "an array of names, for the regions intersected by the current feature"
    },
    {
      "expression": "array_to_string(overlay_intersects('regions', name))",
      "returns": "a string as a comma separated list of names, for the regions intersected by the current feature"
    },
    {
      "expression": "array_sort(overlay_intersects(layer:='regions', expression:=\"name\", filter:= population > 10000))",
      "returns": "an ordered array of names, for the regions intersected by the current feature and with a population greater than 10000"
    },
    {
      "expression": "overlay_intersects(layer:='regions', expression:= geom_to_wkt(@geometry), limit:=2)",
      "returns": "an array of geometries (in WKT), for up to two regions intersected by the current feature"
    },
    {
      "expression": "overlay_intersects(layer:='regions', min_overlap:=0.54)",
      "returns": "TRUE if the current feature spatially intersects a region and the intersection area (of at least one of the parts in case of multipolygons) is greater or equal to 0.54"
    },
    {
      "expression": "overlay_intersects(layer:='regions', min_inscribed_circle_radius:=0.54)",
      "returns": "TRUE if the current feature spatially intersects a region and the intersection area maximum inscribed circle's radius (of at least one of the parts in case of multipart) is greater or equal to 0.54"
    },
    {
      "expression": "overlay_intersects(layer:='regions', expression:= geom_to_wkt(@geometry), return_details:=true)",
      "returns": "an array of maps containing 'id', 'result', 'overlap' and 'radius'"
    },
    {
      "expression": "overlay_intersects(layer:='regions', expression:= geom_to_wkt(@geometry), sort_by_intersection_size:='des')",
      "returns": "an array of geometries (in WKT) ordered by the overlap value in descending order"
    }
  ],
  "tags": ["intersected", "predicate", "current", "target", "array", "geos", "postgis", "described", "st_intersects", "intersects", "underlying", "features"]
}