Skip to content

Adds new expression functions #10870

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
DelazJ wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Adds new expression functions #10870

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
47f4a9f
Add functions for geometry equality and link them together
DelazJ Mar 29, 2026
ae19396
Add operators for color manipulation
DelazJ Mar 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
198 changes: 196 additions & 2 deletions docs/user_manual/expressions/expression_help/GeometryGroup.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -735,7 +735,7 @@ Returns the last node from a geometry.
equals
......

Tests whether two geometries are equal. Note that the order of their vertices matters. Returns TRUE if geometry1 is exactly equal to geometry2.
Alias for 'exactly_equals' with default geometry backend QGIS. Tests whether two geometries are equal. Note that the order of their vertices matters. Returns TRUE if geometry1 is exactly equal to geometry2.

.. list-table::
:widths: 15 85
Expand All @@ -755,6 +755,36 @@ Tests whether two geometries are equal. Note that the order of their vertices ma

.. end_equals_section

.. _expression_function_GeometryGroup_exactly_equals:

exactly_equals
..............

Tests whether two geometries are exactly equal. Note that the order of their vertices matters. Returns TRUE if geometry1 is exactly equal to geometry2.

.. list-table::
:widths: 15 85

* - Syntax
- exactly_equals(geometry1, geometry2, [backend=QGIS])

[] marks optional arguments
* - Arguments
- * **geometry1** - a geometry
* **geometry2** - a geometry
* **backend** - Geometry backend implementation: QGIS or GEOS
* - Examples
- * ``exactly_equals( geom_from_wkt( 'POINT( 0 0 )' ), geom_from_wkt( 'POINT( 0 0 )' ) )`` → TRUE
* ``exactly_equals( geom_from_wkt( 'POINT( 0 0 )' ), geom_from_wkt( 'POINT( 0 0 )' ), 'QGIS' )`` → TRUE
* ``exactly_equals( geom_from_wkt( 'POINT( 0 0 )' ), geom_from_wkt( 'MULTIPOINT( ( 0 0 ) )' ) )`` → FALSE
* ``exactly_equals( geom_from_wkt( 'POINT( 0 0 )' ), geom_from_wkt( 'MULTIPOINT( ( 0 0 ) )' ), 'GEOS' )`` → FALSE
* ``exactly_equals( geom_from_wkt( 'LINESTRING( 0 0, 1 1 )' ), geom_from_wkt( 'LINESTRING( 0 0, 1 1 )' ) )`` → TRUE
* ``exactly_equals( geom_from_wkt( 'LINESTRING( 0 0, 1 1 )' ), geom_from_wkt( 'LINESTRING( 1 1, 0 0 )' ) )`` → FALSE
* ``exactly_equals( geom_from_wkt( 'POLYGON(( 0 0, 0 1, 1 1, 0 0 ))' ), geom_from_wkt( 'POLYGON(( 0 0, 1 1, 0 1, 0 0 ))' ) )`` → FALSE


.. end_exactly_equals_section

.. _expression_function_GeometryGroup_exif_geotag:

exif_geotag
Expand Down Expand Up @@ -937,6 +967,36 @@ Forces a geometry to respect the Right-Hand-Rule, in which the area that is boun

.. end_force_rhr_section

.. _expression_function_GeometryGroup_fuzzy_equals:

fuzzy_equals
............

Tests whether two geometries are fuzzy equal. Note that the order of their vertices matters. Returns TRUE if geometry1 is fuzzy equal to geometry2.

.. list-table::
:widths: 15 85

* - Syntax
- fuzzy_equals(geometry1, geometry2, [backend=QGIS], [epsilon=1e-8])

[] marks optional arguments
* - Arguments
- * **geometry1** - a geometry
* **geometry2** - a geometry
* **backend** - Geometry backend implementation: QGIS or GEOS
* **epsilon** - maximum difference for coordinates between the objects
* - Examples
- * ``fuzzy_equals( geom_from_wkt( 'POINT( 0 0 )' ), geom_from_wkt( 'POINT( 0 0 )' ) )`` → TRUE
* ``fuzzy_equals( geom_from_wkt( 'POINT( 0 0 )' ), geom_from_wkt( 'POINT( 0.5 0.5 )' ), epsilon:=1 )`` → TRUE
* ``fuzzy_equals( geom_from_wkt( 'POINT( 0 0 )' ), geom_from_wkt( 'MULTIPOINT( ( 0 0 ) )' ) )`` → FALSE
* ``fuzzy_equals( geom_from_wkt( 'POINT( 0 0 )' ), geom_from_wkt( 'MULTIPOINT( ( 0 0 ) )' ), 'GEOS' )`` → TRUE
* ``fuzzy_equals( geom_from_wkt( 'LINESTRING( 0 0, 1 1 )' ), geom_from_wkt( 'LINESTRING( 0 0, 1.5 1.5 )' ), 'GEOS', 0.8 )`` → TRUE
* ``fuzzy_equals( geom_from_wkt( 'LINESTRING( 0 0, 1 1 )' ), geom_from_wkt( 'LINESTRING( 0 0, 1.5 1.5 )' ), 'QGIS', 0.8 )`` → TRUE


.. end_fuzzy_equals_section

.. _expression_function_GeometryGroup_geom_from_gml:

geom_from_gml
Expand Down Expand Up @@ -2388,7 +2448,7 @@ Read more on the underlying GEOS "Disjoint" predicate, as described in PostGIS `
overlay_equals
..............

Returns whether the current feature's geometry is exactly equal to at least one feature's geometry from a target layer, or returns an array of expression-based results for the features in the target layer whose geometry is exactly equal to the current feature's geometry. Note that the order of vertices matters.
Alias for 'overlay_exactly_equals' with default geometry backend QGIS. Returns whether the current feature's geometry is exactly equal to at least one feature's geometry from a target layer, or returns an array of expression-based results for the features in the target layer whose geometry is exactly equal to the current feature's geometry. Note that the order of vertices matters.

.. list-table::
:widths: 15 85
Expand Down Expand Up @@ -2416,6 +2476,77 @@ Returns whether the current feature's geometry is exactly equal to at least one

.. end_overlay_equals_section

.. _expression_function_GeometryGroup_overlay_exactly_equals:

overlay_exactly_equals
......................

Returns whether the current feature's geometry is exactly equal to at least one feature's geometry from a target layer, or returns an array of expression-based results for the features in the target layer whose geometry is exactly equal to the current feature's geometry. Note that the order of vertices matters.

.. list-table::
:widths: 15 85

* - Syntax
- overlay_exactly_equals(layer, [expression], [filter], [limit], [cache=false], [backend=QGIS])

[] marks optional arguments
* - Arguments
- * **layer** - the layer whose overlay is checked
* **expression** - 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.
* **filter** - an optional expression to filter the target features to check. If not set, all the features will be checked.
* **limit** - an optional integer to limit the number of matching features. If not set, all the matching features will be returned.
* **cache** - 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)
* **backend** - Geometry backend implementation: QGIS or GEOS
* - Examples
- * ``overlay_exactly_equals('regions')`` → TRUE if the current feature's geometry is exactly the same as the geometry of a region
* ``overlay_exactly_equals('regions', filter:= population > 10000)`` → TRUE if the current feature's geometry is exactly the same as the geometry of a region whose population is greater than 10000
* ``overlay_exactly_equals('regions', name)`` → an array of names, for the regions exactly equal to the current feature
* ``overlay_exactly_equals('regions', name, backend:='QGIS')`` → an array of names, for the regions exactly equal to the current feature
* ``array_to_string(overlay_exactly_equals('regions', name))`` → a string as a comma separated list of names, for the regions exactly equal to the current feature
* ``array_sort(overlay_exactly_equals(layer:='regions', expression:="name", filter:= population > 10000))`` → an ordered array of names, for the regions exactly equal to the current feature and with a population greater than 10000
* ``overlay_exactly_equals(layer:='regions', expression:= geom_to_wkt(@geometry), limit:=2)`` → an array of geometries (in WKT), for up to two regions exactly equal to the current feature

.. note:: This function requires exact equality of geometries, meaning that the geometries 'LINESTRING( 0 0, 1 1 )' and 'LINESTRING( 1 1, 0 0 )' are different.


.. end_overlay_exactly_equals_section

.. _expression_function_GeometryGroup_overlay_fuzzy_equals:

overlay_fuzzy_equals
....................

Returns whether the current feature's geometry is fuzzy equal to at least one feature's geometry from a target layer, or returns an array of expression-based results for the features in the target layer whose geometry is fuzzy equal to the current feature's geometry. Note that the order of vertices matters.

.. list-table::
:widths: 15 85

* - Syntax
- overlay_fuzzy_equals(layer, [expression], [filter], [limit], [cache=false], [backend=QGIS], [epsilon=1e-8])

[] marks optional arguments
* - Arguments
- * **layer** - the layer whose overlay is checked
* **expression** - 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.
* **filter** - an optional expression to filter the target features to check. If not set, all the features will be checked.
* **limit** - an optional integer to limit the number of matching features. If not set, all the matching features will be returned.
* **cache** - 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)
* **backend** - Geometry backend implementation: QGIS or GEOS
* **epsilon** - maximum difference for coordinates between the objects
* - Examples
- * ``overlay_fuzzy_equals('regions')`` → TRUE if the current feature's geometry is fuzzy the same as the geometry of a region
* ``overlay_fuzzy_equals('regions', filter:= population > 10000)`` → TRUE if the current feature's geometry is fuzzy the same as the geometry of a region whose population is greater than 10000
* ``overlay_fuzzy_equals('regions', name)`` → an array of names, for the regions fuzzy equal to the current feature
* ``overlay_fuzzy_equals('regions', name, backend:='QGIS')`` → an array of names, for the regions fuzzy equal to the current feature
* ``array_to_string(overlay_fuzzy_equals('regions', name, epsilon:=0.5))`` → a string as a comma separated list of names, for the regions fuzzy equal to the current feature
* ``array_sort(overlay_fuzzy_equals(layer:='regions', expression:="name", filter:= population > 10000))`` → an ordered array of names, for the regions fuzzy equal to the current feature and with a population greater than 10000
* ``overlay_fuzzy_equals(layer:='regions', expression:= geom_to_wkt(@geometry), limit:=2)`` → an array of geometries (in WKT), for up to two regions fuzzy equal to the current feature

.. note:: This function requires exact equality of geometries, meaning that the geometries 'LINESTRING( 0 0, 1 1 )' and 'LINESTRING( 1 1, 0 0 )' are different.


.. end_overlay_fuzzy_equals_section

.. _expression_function_GeometryGroup_overlay_intersects:

overlay_intersects
Expand Down Expand Up @@ -2503,6 +2634,41 @@ Note: This function can be slow and consume a lot of memory for large layers.

.. end_overlay_nearest_section

.. _expression_function_GeometryGroup_overlay_topologically_equals:

overlay_topologically_equals
............................

Returns whether the current feature's geometry is topologically equal to at least one feature's geometry from a target layer, or returns an array of expression-based results for the features in the target layer whose geometry is topologically equal to the current feature's geometry. Note that the order of vertices matters.

.. list-table::
:widths: 15 85

* - Syntax
- overlay_topologically_equals(layer, [expression], [filter], [limit], [cache=false], [backend=GEOS])

[] marks optional arguments
* - Arguments
- * **layer** - the layer whose overlay is checked
* **expression** - 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.
* **filter** - an optional expression to filter the target features to check. If not set, all the features will be checked.
* **limit** - an optional integer to limit the number of matching features. If not set, all the matching features will be returned.
* **cache** - 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)
* **backend** - Geometry backend implementation: GEOS
* - Examples
- * ``overlay_topologically_equals('regions')`` → TRUE if the current feature's geometry is topologically the same as the geometry of a region
* ``overlay_topologically_equals('regions', filter:= population > 10000)`` → TRUE if the current feature's geometry is topologically the same as the geometry of a region whose population is greater than 10000
* ``overlay_topologically_equals('regions', name)`` → an array of names, for the regions topologically equal to the current feature
* ``overlay_topologically_equals('regions', name, backend:='GEOS')`` → an array of names, for the regions topologically equal to the current feature
* ``array_to_string(overlay_topologically_equals('regions', name))`` → a string as a comma separated list of names, for the regions topologically equal to the current feature
* ``array_sort(overlay_topologically_equals(layer:='regions', expression:="name", filter:= population > 10000))`` → an ordered array of names, for the regions topologically equal to the current feature and with a population greater than 10000
* ``overlay_topologically_equals(layer:='regions', expression:= geom_to_wkt(@geometry), limit:=2)`` → an array of geometries (in WKT), for up to two regions topologically equal to the current feature

.. note:: This function requires exact equality of geometries, meaning that the geometries 'LINESTRING( 0 0, 1 1 )' and 'LINESTRING( 1 1, 0 0 )' are different.


.. end_overlay_topologically_equals_section

.. _expression_function_GeometryGroup_overlay_touches:

overlay_touches
Expand Down Expand Up @@ -3223,6 +3389,34 @@ Creates a buffer along a line geometry where the buffer diameter varies evenly o

.. end_tapered_buffer_section

.. _expression_function_GeometryGroup_topologically_equals:

topologically_equals
....................

Tests whether two geometries are topologically equal. Note that the order of their vertices matters. Returns TRUE if geometry1 is topologically equal to geometry2.

.. list-table::
:widths: 15 85

* - Syntax
- topologically_equals(geometry1, geometry2, [backend=GEOS])

[] marks optional arguments
* - Arguments
- * **geometry1** - a geometry
* **geometry2** - a geometry
* **backend** - Geometry backend implementation: GEOS
* - Examples
- * ``topologically_equals( geom_from_wkt( 'POINT( 0 0 )' ), geom_from_wkt( 'POINT( 0 0 )' ) )`` → TRUE
* ``topologically_equals( geom_from_wkt( 'POINT( 0 0 )' ), geom_from_wkt( 'POINT( 0 0 )' ), 'GEOS' )`` → TRUE
* ``topologically_equals( geom_from_wkt( 'POINT( 0 0 )' ), geom_from_wkt( 'MULTIPOINT( ( 0 0 ) )' ) )`` → TRUE
* ``topologically_equals( geom_from_wkt( 'POINT( 0 0 )' ), geom_from_wkt( 'MULTIPOINT( ( 0 0 ) )' ), 'GEOS' )`` → TRUE
* ``topologically_equals( geom_from_wkt( 'LINESTRING( 0 0, 1 1 )' ), geom_from_wkt( 'LINESTRING( 0 0, 1 1 )' ) )`` → TRUE


.. end_topologically_equals_section

.. _expression_function_GeometryGroup_touches:

touches
Expand Down
40 changes: 38 additions & 2 deletions docs/user_manual/expressions/expression_help/Operators.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,15 @@ Remainder of division. Takes the sign of the dividend.
\*
..

Multiplication of two values
Multiplication of two values.



When used with two colors, performs component-wise multiplication on the color components (not alpha), clamping results to [0, 1]. The alpha channel of the left color is used. HSL and HSV colors are converted to RGB for the operation, and the result is an RGB color. CMYK colors produce a CMYK result.



When used with a color and a number (in any order), multiplies each color component (excluding alpha) by the number, clamping results to [0, 1]. The alpha channel is preserved.

.. list-table::
:widths: 15 85
Expand All @@ -48,6 +56,7 @@ Multiplication of two values
* - Examples
- * ``5 * 4`` → 20
* ``5 * NULL`` → NULL
* ``color_rgbf(0.2, 0.4, 0.6) * 2`` → RGBA: 0.40,0.80,1.00,1.00


.. end_*_section
Expand All @@ -67,6 +76,14 @@ For numeric and datetime operations if either value is NULL the result will be N

For string concatenation NULL values from fields are treated as empty strings. Use the || operator instead if NULL propagation for strings is required.



When used with two colors, performs component-wise addition on the color components (not alpha), clamping results to [0, 1]. The alpha channel of the left color is used. HSL and HSV colors are converted to RGB for the operation, and the result is an RGB color. CMYK colors produce a CMYK result.



When used with a color and a number (in any order), adds the number to each color component (excluding alpha), clamping results to [0, 1]. The alpha channel is preserved.

.. list-table::
:widths: 15 85

Expand All @@ -82,6 +99,7 @@ For string concatenation NULL values from fields are treated as empty strings. U
* ``'5' + "name"`` → '5' (if value in "name" field is NULL) or a concatenation of the two strings
* ``'QGIS ' + 'ROCKS'`` → 'QGIS ROCKS'
* ``to_datetime('2020-08-01 12:00:00') + '1 day 2 hours'`` → 2020-08-02T14:00:00
* ``color_rgbf(0.2, 0.4, 0.6) + 0.1`` → RGBA: 0.30,0.50,0.70,1.00


.. end_+_section
Expand All @@ -93,6 +111,14 @@ For string concatenation NULL values from fields are treated as empty strings. U

Subtraction of two values. If one of the values is NULL the result will be NULL.



When used with two colors, performs component-wise subtraction on the color components (not alpha), clamping results to [0, 1]. The alpha channel of the left color is used. HSL and HSV colors are converted to RGB for the operation, and the result is an RGB color. CMYK colors produce a CMYK result.



When used with a color and a number (in any order), subtracts one from the other per color component (excluding alpha), clamping results to [0, 1]. The alpha channel is preserved.

.. list-table::
:widths: 15 85

Expand All @@ -105,6 +131,7 @@ Subtraction of two values. If one of the values is NULL the result will be NULL.
- * ``5 - 4`` → 1
* ``5 - NULL`` → NULL
* ``to_datetime('2012-05-05 12:00:00') - to_interval('1 day 2 hours')`` → 2012-05-04T10:00:00
* ``color_rgbf(0.8, 0.6, 0.4) - 0.1`` → RGBA: 0.70,0.50,0.30,1.00


.. end_-_section
Expand All @@ -114,7 +141,15 @@ Subtraction of two values. If one of the values is NULL the result will be NULL.
/
.

Division of two values
Division of two values.



When used with two colors, performs component-wise division on the color components (not alpha), clamping results to [0, 1]. The alpha channel of the left color is used. HSL and HSV colors are converted to RGB for the operation, and the result is an RGB color. CMYK colors produce a CMYK result.



When used with a color and a number, divides each color component (excluding alpha) by the number, clamping results to [0, 1]. The color must be on the left side. Division by zero returns NULL. The alpha channel is preserved.

.. list-table::
:widths: 15 85
Expand All @@ -127,6 +162,7 @@ Division of two values
* - Examples
- * ``5 / 4`` → 1.25
* ``5 / NULL`` → NULL
* ``color_rgbf(0.8, 0.6, 0.4) / 2`` → RGBA: 0.40,0.30,0.20,1.00


.. end_/_section
Expand Down
Loading
Loading