Three new simple but useful spatial functions by craigtaverner · Pull Request #144703 · elastic/elasticsearch

craigtaverner · 2026-03-21T20:16:18Z

Three new simple but useful spatial functions, particularly when testing ST_CENTROID_AGG which takes topological dimension into account during aggregations:

ST_Dimension (topological dimension)
- The topological dimension is 0 for points, 1 for lines and 2 for polygons. This is important in understanding how centroids are calculated in ST_CENTROID_AGG, where higher dimensions completely remove the contribution from lower ones.
- See the PostGIS equivalent at https://postgis.net/docs/ST_Dimension.html
ST_GeometryType
- A string name of the geometry type: ST_Point, ST_LineString, etc.
- See the PostGIS equivalent at https://postgis.net/docs/ST_GeometryType.html
ST_IsEmpty
- A boolean flag for whether the geometry is empty or not
- See PostGIS equivalent at https://postgis.net/docs/ST_IsEmpty.html

The ST_GeometryType and ST_Dimension functions also include a specific optimization for point types, since they will always return a constant values for all non-null results. This had a noticable effect on the macro-benchmarks results for the geopoint track:

Task	Without constant evaluator	With constant evaluator	Improvement
st-geometrytype-stats-esql	462.121	98.4184	80%
st-dimension-stats-esql	159.484	150.169	6%
st-isempty-stats-esql	124.098	126.023	0%

* ST_Dimension (topological dimension) as in https://postgis.net/docs/ST_Dimension.html * ST_GeometryType (string name of geometry type) as in https://postgis.net/docs/ST_GeometryType.html * ST_IsEmpty (boolean) as in https://postgis.net/docs/ST_IsEmpty.html

elasticsearchmachine · 2026-03-21T20:16:44Z

Pinging @elastic/es-analytical-engine (Team:Analytics)

elasticsearchmachine · 2026-03-21T20:17:07Z

Hi @craigtaverner, I've created a changelog YAML for you.

github-actions · 2026-03-21T20:19:59Z

🔍 Preview links for changed docs

github-actions · 2026-03-21T20:20:00Z

ℹ️ Important: Docs version tagging

👋 Thanks for updating the docs! Just a friendly reminder that our docs are now cumulative. This means all 9.x versions are documented on the same page and published off of the main branch, instead of creating separate pages for each minor version.

We use applies_to tags to mark version-specific features and changes.

Expand for a quick overview

When to use applies_to tags:

✅ At the page level to indicate which products/deployments the content applies to (mandatory)
✅ When features change state (e.g. preview, ga) in a specific version
✅ When availability differs across deployments and environments

What NOT to do:

❌ Don't remove or replace information that applies to an older version
❌ Don't add new information that applies to a specific version without an applies_to tag
❌ Don't forget that applies_to tags can be used at the page, section, and inline level

🤔 Need help?

Check out the cumulative docs guidelines
Reach out in the #docs Slack channel

…asticsearch into three_spatial_functions

…ible

This was previously a much larger change, based on double-checking that the constant block optimization actually made an improvement in macro benchmarks, which it did (a lot for ST_GEOMETRYTYPE and a small amount for ST_DIMENSION).

shainaraskas · 2026-03-24T16:20:16Z

+      - to: 'reference/query-languages/esql/functions-operators/spatial-functions/st_geometrytype.md'
+        anchors: {'esql-st_geometrytype'}
+      - to: 'reference/query-languages/esql/functions-operators/spatial-functions/st_dimension.md'
+        anchors: {'esql-st_dimension'}
+      - to: 'reference/query-languages/esql/functions-operators/spatial-functions/st_isempty.md'
+        anchors: {'esql-st_isempty'}


if these functions are new (e.g. docs content is not being moved from one location to another), then no redirects should be needed

Thanks, removing them now.

ncordon

Left a few improvements but nothing major to correct

ncordon · 2026-03-24T12:25:46Z

+            for (Geometry geometry : collection) {
+                maxDimension = Math.max(maxDimension, geometry.visit(this));
+            }


I think we could short circuit this is we are already at dimension 2?

if (maxDimension == 2) { break; }

ncordon · 2026-03-24T12:35:42Z

+
+        @Override
+        public long baseRamBytesUsed() {
+            return field.baseRamBytesUsed();


Shouldn't we include the shallow size here?

Good catch. I've changed to to look more like what we see in StDimensionFromWKBEvaluator.

ncordon · 2026-03-24T18:06:17Z

+            case GEOMETRYCOLLECTION -> "ST_GeometryCollection";
+            case LINEARRING -> "ST_LineString";
+            case ENVELOPE -> "ST_Polygon";
+            case CIRCLE -> "ST_Point";


We discussed changing this to be a line (probably a St_Polygon?)

Done! And I did a search for OGC compliance for the option of ST_Circle and that is not OGC compliant, so we stick with ST_Polygon.

ncordon · 2026-03-24T18:09:30Z

+            BytesRef wkb = wkbBlock.getBytesRef(firstValueIndex + i, scratch);
+            Geometry geometry = UNSPECIFIED.wkbToGeometry(wkb);
+            int dimension = geometry.visit(DIMENSION_VISITOR);
+            maxDimension = Math.max(maxDimension, dimension);


Same here, we could short circuit in the case we've reached the max dimension true?

Great idea. I added an extra condition to the for loop a few lines above.

Three new simple but useful spatial functions, particularly when testing `ST_CENTROID_AGG` which takes topological dimension into account during aggregations: * `ST_Dimension` (topological dimension) * The topological dimension is 0 for points, 1 for lines and 2 for polygons. This is important in understanding how centroids are calculated in ST_CENTROID_AGG, where higher dimensions completely remove the contribution from lower ones. * See the PostGIS equivalent at https://postgis.net/docs/ST_Dimension.html * `ST_GeometryType` * A string name of the geometry type: ST_Point, ST_LineString, etc. * See the PostGIS equivalent at https://postgis.net/docs/ST_GeometryType.html * `ST_IsEmpty` * A boolean flag for whether the geometry is empty or not * See PostGIS equivalent at https://postgis.net/docs/ST_IsEmpty.html The `ST_GeometryType` and `ST_Dimension` functions also include a specific optimization for point types, since they will always return a constant values for all non-null results. This had a noticable effect on the macro-benchmarks results for the geopoint track: | Task | Without constant evaluator | With constant evaluator | Improvement | | --- | --- | --- | --- | | st-geometrytype-stats-esql | 462.121 | 98.4184 | 80% | | st-dimension-stats-esql | 159.484 | 150.169 | 6% | | st-isempty-stats-esql | 124.098 | 126.023 | 0% |

craigtaverner requested a review from a team as a code owner March 21, 2026 20:16

craigtaverner added >enhancement :Analytics/Geo Indexing, search aggregations of geo points and shapes Team:Analytics Meta label for analytical engine team (ESQL/Aggs/Geo) :Analytics/ES|QL AKA ESQL labels Mar 21, 2026

craigtaverner requested review from ncordon and removed request for a team March 21, 2026 20:16

elasticsearchmachine added the v9.4.0 label Mar 21, 2026

Update docs/changelog/144703.yaml

8cc296a

elasticsearchmachine and others added 7 commits March 21, 2026 20:24

[CI] Auto commit changes from spotless

49c386b

Add missing function error tests

a6ed426

Renamed StGeohexErrorTests

0cc1395

Merge branch 'three_spatial_functions' of github.com:craigtaverner/el…

3849841

…asticsearch into three_spatial_functions

Fixed changelog

7241922

Update docs to link in new functions

d09d7c0

Optimize ST_DIMENSION for points, using constant blocks where possible

4884ed1

craigtaverner requested a review from a team as a code owner March 21, 2026 20:58

craigtaverner and others added 7 commits March 21, 2026 22:06

Optimize ST_GEOMETRYTYPE for points, using constant blocks where poss…

d26af1e

…ible

Added more tests, yaml tests for missing geometries

aeab57e

Added multivalue csv-spec tests

24ee5ea

Nicer examples formatting for docs

412b4d8

Added physical optimizer tests to ensure doc-values are used

e6dfbc3

Simplify if statement

5770732

This was previously a much larger change, based on double-checking that the constant block optimization actually made an improvement in macro benchmarks, which it did (a lot for ST_GEOMETRYTYPE and a small amount for ST_DIMENSION).

[CI] Auto commit changes from spotless

b33dd94

craigtaverner mentioned this pull request Mar 22, 2026

Three new spatial functions elastic/rally-tracks#1101

Open

shainaraskas reviewed Mar 24, 2026

View reviewed changes

ncordon approved these changes Mar 24, 2026

View reviewed changes

craigtaverner added 2 commits March 25, 2026 12:01

Merge remote-tracking branch 'origin/main' into three_spatial_functions

7a519df

Code review updates

09c9e52

craigtaverner added the auto-merge-without-approval Automatically merge pull request when CI checks pass (NB doesn't wait for reviews!) label Mar 25, 2026

elasticsearchmachine merged commit 3ba52bd into elastic:main Mar 25, 2026
36 checks passed

craigtaverner deleted the three_spatial_functions branch March 25, 2026 15:38

Conversation

craigtaverner commented Mar 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

elasticsearchmachine commented Mar 21, 2026

Uh oh!

elasticsearchmachine commented Mar 21, 2026

Uh oh!

github-actions Bot commented Mar 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

github-actions Bot commented Mar 21, 2026

ℹ️ Important: Docs version tagging

When to use applies_to tags:

What NOT to do:

🤔 Need help?

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ncordon left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

craigtaverner commented Mar 21, 2026 •

edited

Loading

github-actions Bot commented Mar 21, 2026 •

edited

Loading