WL#8055: Consistent naming scheme for GIS functions - Deprecation
This WL is about cleaning up the GIS function namespace by deprecating, removing and adding function names (aliases) in order to make the naming scheme consistent and bring MySQL in line with other major DBMSs. The standard among DBMSs is to use an "ST_" prefix to function names, as specified by SQL/MM. PostGIS, Oracle and most other systems follow this naming scheme, while Microsoft SQL Server uses "ST" without the underscore. In MySQL, almost all GIS functions have multiple names. Most functions have two names: one with an "ST_" prefix, and one without, e.g., "ST_SRID" and "SRID". Newer functions are implemented only with an "ST_" prefix, while some older functions only have a name without the prefix. Some functions have two implementations: one that gives an exact answer, and one "MBR" implementation that uses a minimum bounding rectangle instead of the exact shape of objects, e.g., "ST_Contains" and "MBRContains". For most of these functions, there is also a third name without a prefix, e.g., "Contains". The name without a prefix mostly points to the MBR functions, but not always. In one case, the non-prefixed function name collides with an existing function, so the non-prefixed version of "ST_Length" is "GLength" ("Length" calculates the length of a string). This WL will standardize on "ST_" prefixed functions by making the following changes: - Add "ST_" prefixed function names for functions that don't have them (except "MBR" prefixed functions). - Deprecate function names without an "ST_" or "MBR" prefix. The only exception to this standardization is the geometry object construction functions Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon and GeometryCollection. These functions have the same name as the corresponding column type and will not be deprecated or receive an "ST_" prefix. In total, 66 function names are deprecated, and 13 are added.
Functional requirements: F-1: The following functions MUST cause a completion condition to be raised with the ER_WARN_DEPRECATED_SYNTAX warning message telling the user to use the "MBR" prefixed name instead: Contains Disjoint Equals Intersects Overlaps Within F-2: The following functions MUST cause a completion condition to be raised with the ER_WARN_DEPRECATED_SYNTAX warning message telling the user to use the "ST_" prefixed name instead. Area AsBinary AsText AsWKB AsWKT Buffer Centroid ConvexHull Crosses Dimension Distance EndPoint Envelope ExteriorRing GeometryN GeometryType InteriorRingN IsClosed IsEmpty IsSimple NumGeometries NumInteriorRings NumPoints PointN SRID StartPoint Touches X Y F-3: The "GLength" function MUST cause a completion condition to be raised with the ER_WARN_DEPRECATED_SYNTAX warning message telling the user to use the "ST_Length" function instead. F-4: The following functions MUST cause a completion condition to be raised with the ER_WARN_DEPRECATED_SYNTAX warning message telling the user to use the "ST_" prefixed name instead. GeomCollFromText GeomCollFromWKB GeometryCollectionFromText GeometryCollectionFromWKB GeometryFromText GeometryFromWKB GeomFromText GeomFromWKB LineFromText LineFromWKB LineStringFromText LineStringFromWKB MLineFromText MLineFromWKB MPointFromText MPointFromWKB MPolyFromText MPolyFromWKB MultiLineStringFromText MultiLineStringFromWKB MultiPointFromText MultiPointFromWKB MultiPolygonFromText MultiPolygonFromWKB PointFromText PointFromWKB PolyFromText PolyFromWKB PolygonFromText PolygonFromWKB F-5: The following new function names MUST be added and refer to the same function as without the "ST_" prefix: ST_GeomCollFromTxt ST_MLineFromText ST_MLineFromWKB ST_MPointFromText ST_MPointFromWKB ST_MPolyFromText ST_MPolyFromWKB ST_MultiLineStringFromText ST_MultiLineStringFromWKB ST_MultiPointFromText ST_MultiPointFromWKB ST_MultiPolygonFromText ST_MultiPolygonFromWKB F-6: The functions in F-5 MUST NOT raise a completion condition with the ER_WARN_DEPRECATED_SYNTAX warning message.
Changes to the interface specification: I-1: No new files. I-2: New syntax: 13 new functions: ST_GeomCollFromTxt(<wkt>[, <srid>]) ST_MLineFromText(<wkt>[, <srid>]) ST_MLineFromWKB(<wkt>[, <srid>]) ST_MPointFromText(<wkt>[, <srid>]) ST_MPointFromWKB(<wkt>[, <srid>]) ST_MPolyFromText(<wkt>[, <srid>]) ST_MPolyFromWKB(<wkt>[, <srid>]) ST_MultiLineStringFromText(<wkt>[, <srid>]) ST_MultiLineStringFromWKB(<wkt>[, <srid>]) ST_MultiPointFromText(<wkt>[, <srid>]) ST_MultiPointFromWKB(<wkt>[, <srid>]) ST_MultiPolygonFromText(<wkt>[, <srid>]) ST_MultiPolygonFromWKB(<wkt>[, <srid>]) I-3: No new commands. I-4: No new tools. I-5: No impact on existing functionality.
Deprecation of function names ============================= Before this WL, it is not possible to know which function alias that was used when the query was sent from the user. So in order to identify which function alias that was used, we need an extra field in Item class: In Item.h: - Add public field to Item class: char *function_alias_used= NULL; This field will be populated in PTI_function_call_generic_ident_sys::itemize(), when the native functions are resolved. This is the stage where we know which alias was used when the query was sent from the user. For each function to be deprecated, we can use this field do determine whether we should raise a deprecation warning or not. For instance, for Area() the code will look something like this: if (native_strcasecmp("area", this->function_alias_used) == 0) push_deprecated_warn(current_thd, "AREA", "ST_AREA"); This code snippet will be added in each functions val_*-function, so that one warning is raised for each row evaluated. Some initial testing shows that string comparison should not cause any performance issues at all. Adding new function names ========================= For each of the new function names to be added in F-5, we add a new entry in Item_create::func_array, which refers to the correct Create_func-class. For instance, ST_MultiLineStringFromText will refer to the class Create_func_geometry_from_text. Test suite ========== All test that uses any of the deprecated spatial functions must be changed and re-recorded to use the correct function alias. A new test file named deprecated_functions.test will be added to MTR to ensure that all deprecated spatial functions do raise a ER_WARN_DEPRECATED_SYNTAX warning.
Copyright (c) 2000, 2019, Oracle Corporation and/or its affiliates. All rights reserved.