GeoAnalytics Engine 2.0 Breaking Changes: What You Need to Know

SBattersby · ‎03-26-2026

With the release of GeoAnalytics Engine 2.0, changes have been introduced that may impact workflows, development practices, and compatibility. In this post, we’ll not only outline the breaking changes but also include code examples to illustrate what’s new, guiding you through each one step by step.

Why Breaking Changes?

Breaking changes are designed to improve performance, code maintainability, and developer experience. While backward compatibility is often a goal, some updates require rethinking established patterns.

Strategies for Adapting

Read the Release Notes: The GeoAnalytics Engine documentation has details on the 2.0 release that will provide good reference.
Check the code samples and API guide: If you encounter unexpected errors, check the developer documentation code samples and the API guide to ensure that there aren’t changes that you need to accommodate in your script.
Update Incrementally: Upgrade your code and dependencies step by step, testing thoroughly after each change.
Engage the Community: Ask questions and share experiences on the GeoAnalytics Engine Community if you encounter issues.

Breaking changes overview

We will divide the changes into four sections:

Supported environments
SQL functions
Track functions
Tools

Supported Environments

Change: In GeoAnalytics 2.0, the following runtimes will no longer be supported. These runtimes were previously supported in version 1.7.x.

Spark 3.2.x
Spark 3.3.x
Amazon EMR 6.6.x – 6.11.x
Databricks 12.2 LTS
Google Dataproc 2.1-x
Azure Synapse Runtime for Apache Spark 3.4

Mitigation
Update the environment in which you use GeoAnalytics Engine. A list of supported environments is provided in the Developer documentation.

SQL Functions

Some of the SQL functions will have changes to parameter names, inputs, or functionality.

Here is a short summary of changes, with examples to follow:

srid parameter name is replaced by sr
ST_EnvIntersects will no longer accept a set of four min / max coordinates for input
ST_GeodesicBuffer will preserve geographic location of the input geometry's interior by default
ST_FrechetDistance will no longer be callable using a diacritic in the name

For each notable change, we will provide a brief description of the update, as well as a mitigation step. For examples of each of the changes, please refer to the attached PDF document.

srid parameter name is replaced by sr

Change: In GeoAnalytics Engine 2.0, functions that accept a spatial reference as input will no longer support `srid` as a named argument; only `sr` will be recognized starting with 2.0. This argument name was formally deprecated in favor of `sr` starting at version 1.1.0, however, remained as an undocumented legacy input in later versions of 1.x.x.

If the parameter named `srid` is included in a function you will receive an error like this:

TypeError: <function name>() got an unexpected keyword argument 'srid'

This impacts several functions for generating and transforming geometry - documentation for each of these is available in the Developer Documentation for SQL functions:

ST_Point, ST_PointZ, ST_PointZM, ST_PointM, ST_PointFromText, ST_MPointFromText, ST_LineFromText, ST_PolyFromText, ST_GeomFromText, ST_PointFromBinary, ST_MPointFromBinary, ST_LineFromBinary, ST_PolyFromBinary, ST_GeomFromBinary, ST_PointFromEsriJSON, ST_MPointFromEsriJSON, ST_LineFromEsriJSON, ST_PolyFromEsriJSON, ST_GeomFromEsriJSON, ST_PointFromGeoJSON, ST_MPointFromGeoJSON, ST_LineFromGeoJSON, ST_PolyFromGeoJSON, ST_GeomFromGeoJSON, ST_PointFromShape, ST_MPointFromShape, ST_LineFromShape, ST_PolyFromShape, ST_GeomFromShape, ST_Transform

Mitigation
Replace any instances of the parameter name srid with sr

ST_EnvIntersects will no longer accept a set of four min / max coordinates for input

Change: In GeoAnalytics Engine 2.0, ST_EnvIntersects will no longer support passing a geometry column and 4 numbers (x-min, y-min, x-max, and y-max) as input. The only accepted input will be two geometry columns (geometry1, geometry2). This behavior was formally deprecated with GeoAnalytics Engine 1.2.0, however, remained as an undocumented legacy input in later versions of 1.x.x.

If you pass in four named parameters for xmin, ymin, xmax, and ymax you will receive an error like this:

TypeError: env_intersects() got an unexpected keyword argument 'xmin'

If you pass in four unnamed parameters for the x & y coordinates you will receive an error like this:

TypeError: env_intersects() takes 2 positional arguments but 5 were given

Mitigation
Replace your use of ST_EnvIntersects that use 4 bounding coordinates, and use ST_BboxIntersects instead. Refer to the developer documentation and API guide for additional information on the updates to the functions.

ST_GeodesicBuffer will preserve geographic location of the input geometry's interior by default

Change: In GeoAnalytics Engine 2.0, the default behavior of ST_GeodesicBuffer will be changed to preserve the geographic location of the input geometry’s interior, more accurately maintaining its original shape. You may see differences in the geometry returned with ST_GeodesicBuffer if you rely on the default behavior.

Mitigation
To return to the legacy result of the function, set the new “preserve_shape” parameter to False. By default, the parameter is set to True in GeoAnalytics Engine 2.0. Refer to the developer documentation and API guide for additional information on the updates to the function.

ST_FrechetDistance will no longer be callable using a diacritic in the name

Change: In GeoAnalytics Engine 2.0, the ST_FrechetDistance function will no longer be callable using a diacritic in the name (i.e., “ST_FréchetDistance”) due to lack of full support for the diacritic in Apache Spark.

If you use the function name with a diacritic you will receive an error like this:

AttributeError: module 'geoanalytics.sql.functions' has no attribute 'fréchet_distance'

Mitigation
Replace the name for the function to ST_FrechetDistance in any scripts that previously used the function name with a diacritic.

Track Functions

Here is a short summary of changes, with examples to follow:

The output_units (plural) parameter input has changed to output_unit (singular)
Geodesic calculations will be used when one input is unprojected spatial reference and the other has no spatial reference defined
The time input has changed to timestamp in TRK_Aggr_CreateTrack

For each notable change, we will provide a brief description of the update, as well as a mitigation step. For examples of each of the changes, please refer to the attached PDF document.

The output_units parameter input has changed to output_unit

Change: In GeoAnalytics Engine 2.0, the parameter to define the output unit used in track functions has changed from output_units (plural) to output_unit for consistency with other functions and tools in the library. This impacts the following Track functions:

If you use the old naming of output_units you will receive the following error:

TypeError: <function name>() got an unexpected keyword argument 'output_units'

Mitigation
If you use the named parameter output_units in your Track functions, replace with output_unit

Geodesic calculations will be used when one input is unprojected spatial reference and the other has no spatial reference defined

Change: In GeoAnalytics Engine 2.0, several functions will be updated to use geodesic calculations if one input geometry is in an unprojected spatial reference and the other geometry has no spatial reference defined. In GeoAnalytics Engine 1.x.x, these functions use planar distance calculations if the first geometry does not have a defined spatial reference. The functions are:

Mitigation
To replicate the legacy behavior, set the spatial reference of both geometries to 0 (undefined) or a projected spatial reference to force planar distance calculations. Refer to the developer documentation and API guide for additional information on the updates to the Track functions.

The time input has changed to timestamp in TRK_Aggr_CreateTrack

Change: The named parameter to reference timestamps in track data with TRK_Aggr_CreateTrack has changed from "time" to "timestamp" to better reflect the data type required for input.

If you use the old naming of "time" you will receive the following error:

TypeError: aggr_create_track() got an unexpected keyword argument 'time'

Mitigation
If you use the named parameter "time" in TRK_Aggr_CreateTrack, replace with "timestamp"

Tools

Some of the Tools will have changes to input parameters, parameter value names, or content & format of default output.

For each notable change, we will provide a brief description of the update, as well as a mitigation step. For examples of each of the changes, please refer to the attached PDF document.

Here is a short summary of changes, with examples to follow:

Updates to the "setDistanceMethod" setter in Tools when input geometries are projected
The Summarize Within tool will no longer use an "addRateField" setter
The Summarize Within tool will have different outputs depending on run method
The Calculate Motion Statistics tool will ignore track observations with null geometry and/or time
The Reconstruct Tracks tool will include timestamps as m-values in the resulting linestrings by default

Updates to the "setDistanceMethod" setter in Tools when input geometries are projected

Change: In GeoAnalytics 2.0, the "setDistanceMethod" setter will now be required for running tools if the spatial reference of the input geometry column is projected. Additionally, the term "geodesic" has been replaced by the term "geodetic" in "setDistanceMethod," which is a more accurate descriptor of the distance calculation. These changes will apply to the following tools:

If you do not use "setDistanceMethod" with datasets that have projected coordinate systems an error will result:

ValueError: <tool name>.setDistanceMethod required to be called with projected coordinates.

Mitigation
Any scripts using these tools with projected data should be updated to include "setDistanceMethod" to explicitly choose either "planar" or "geodetic" distance calculations. Refer to the developer documentation and API guide for additional information on the updates to these tools.

The Summarize Within tool will no longer use an "addRateField" setter

Change: In GeoAnalytics Engine 2.0, the "addRateField" setter will be removed for the Summarize Within tool. Formerly, fields included in "addRateField" would not be proportioned prior to calculating statistics, whereas other fields would be proportioned by default prior to calculating statistics.

Beginning with version 2.0, proportioning is controlled by the "proportion" parameter in the "addStandardSummaryField" and "addWeightedSummaryField." Set "proportion" to "True" to proportion any field prior to calculating statistics. The default is "False," meaning all fields are not proportioned by default.

The results returned from Summarize Within in version 2.0 will differ from results in 1.x unless the parameters are updated.

Including the "addRateField" setter will result in the following error:

AttributeError: 'SummarizeWithin' object has no attribute 'addRateField'

Mitigation
Any scripts using the Summarize Within tool should be updated to use the new API design, as default statistic results will have changed. Refer to the developer documentation and API guide for additional information on the updates to the tool.

The Summarize Within tool will have different outputs depending on run method

Change: In GeoAnalytics Engine 1.x, the Summarize Within tool returned a named tuple with an "output" DataFrame and a "groupBySummary" result. The pathway to these two results changes with GeoAnalytics Engine 2.0.

In GeoAnalytics Engine 2.0, the Summarize Within tool output has been changed to return a DataFrame if run using the "run" method, and a named tuple if run using the new "runIncludeGroupBy" method. The table type returned from Summarize Within in version 2.0 will differ from results in 1.x depending on how the tool is run.

Note the "setGroupBy" method is required if running the tool using "runIncludeGroupBy."

If your existing scripts rely on ".output" to retrieve the DataFrame resulting from Summarize Within in earlier versions of GeoAnalytics Engine, you will need to remove that from your script. You can then reference the DataFrame directly if you use the "run" method.

Using ".output" when you run Summarize Within using the "run" method will result in the following error:

PySparkAttributeError: [ATTRIBUTE_NOT_SUPPORTED] Attribute output is not supported.

Mitigation
Any scripts using the Summarize Within tool should be updated to use the new API design, as default format and statistic results will have changed. If you only need the DataFrame, use the "run" method to run the tool. If you need "groupBySummary" as well, use "runIncludeGroupBy." Refer to the developer documentation and API guide for additional information on the updates to the tool.

The Calculate Motion Statistics tool will ignore track observations with null geometry and/or time

Change: In GeoAnalytics Engine 2.0, the Calculate Motion Statistics tool will be corrected to ignore track observations with null geometry and/or time. The tool would formerly return null for some statistics in cases where one or more track observations had a null geometry or timestamp. You may see differences in the returned results in version 2.0 as the null geometries will now be ignored.

Mitigation
No mitigation required, however, your output tables may differ from those returned in earlier versions of GeoAnalytics Engine as the null geometries are now ignored.

The Reconstruct Tracks tool will include timestamps as m-values in the resulting linestrings by default

Change: In GeoAnalytics Engine 2.0, the Reconstruct Tracks tool will be updated to include timestamps as m-values in the resulting linestrings by default. This allows the resulting linestrings to be used by TRK functions and other track-related functionality. Any existing m-values in the input points will be overwritten by the timestamps and not included in the result linestrings by default.

Mitigation
To obtain legacy results, call the new “preserveM” setter before running the tool.

Conclusion

This blog post summarizes the breaking changes with GeoAnalytics Engine 2.0. To help clarify the changes, we are also providing an attached notebook with examples of the changes and the mitigation steps for each.

If you have any questions, please let us know in the comments below!