SP-GiST support

CHANGELOG.md

@@ -28,6 +28,7 @@ avoid adding features or APIs which do not map onto the
 
 - Bump `h3` to `v4.2.0`
 - Add `h3_polygon_to_cells_experimental` (see [#159], thanks [@jmealo])
+- Add experimental SP-GIST operator class (see [#43], thanks [@BielStela])
 - Fix for MacOS in nixpkgs / NixOS (see [#141], thanks [@wolfgangwalther])
 
 </details>
@@ -251,6 +252,7 @@ avoid adding features or APIs which do not map onto the
 [#37]: https://github.com/zachasme/h3-pg/issues/37
 [#38]: https://github.com/zachasme/h3-pg/issues/38
 [#41]: https://github.com/zachasme/h3-pg/issues/41
+[#43]: https://github.com/zachasme/h3-pg/issues/43
 [#55]: https://github.com/zachasme/h3-pg/issues/55
 [#64]: https://github.com/zachasme/h3-pg/issues/64
 [#65]: https://github.com/zachasme/h3-pg/pull/65
@@ -274,6 +276,7 @@ avoid adding features or APIs which do not map onto the
 [#160]: https://github.com/zachasme/h3-pg/pull/160
 [@abelvm]: https://github.com/AbelVM
 [@bayandin]: https://github.com/bayandin
+[@BielStela]: https://github.com/BielStela
 [@jmealo]: https://github.com/jmealo
 [@kalenikaliaksandr]: https://github.com/kalenikaliaksandr
 [@kmacdough]: https://github.com/kmacdough

docs/api.md

@@ -470,6 +470,14 @@ Returns true if A contains B.
 Returns true if A is contained by B.
 
 
+## SP-GiST operator class (experimental)
+*This is still an experimental feature and may change in future versions.*
+Add an SP-GiST index using the `h3index_ops_experimental` operator class:
+```sql
+-- CREATE INDEX [indexname] ON [tablename] USING spgist([column] h3index_ops_experimental);
+CREATE INDEX spgist_idx ON h3_data USING spgist(hex h3index_ops_experimental);
+```
+
 # Type casts
 
 ### `h3index` :: `bigint`

h3/CMakeLists.txt

@@ -19,6 +19,7 @@ PostgreSQL_add_extension(postgresql_h3
     src/init.c
     src/opclass_btree.c
     src/opclass_hash.c
+    src/opclass_spgist.c
     src/operators.c
     src/srf.c
     src/type.c
@@ -36,6 +37,7 @@ PostgreSQL_add_extension(postgresql_h3
     sql/install/11-opclass_btree.sql
     sql/install/12-opclass_hash.sql
     sql/install/13-opclass_brin.sql
+    sql/install/14-opclass_spgist.sql
     sql/install/20-casts.sql
     sql/install/30-extension.sql
     sql/install/99-deprecated.sql

h3/sql/install/14-opclass_spgist.sql

@@ -0,0 +1,64 @@
+/*
+ * Copyright 2024 Zacharias Knudsen
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+--| ## SP-GiST operator class (experimental)
+--|
+--| *This is still an experimental feature and may change in future versions.*
+--| Add an SP-GiST index using the `h3index_ops_experimental` operator class:
+--|
+--| ```sql
+--| -- CREATE INDEX [indexname] ON [tablename] USING spgist([column] h3index_ops_experimental);
+--| CREATE INDEX spgist_idx ON h3_data USING spgist(hex h3index_ops_experimental);
+--| ```
+
+--@ internal
+CREATE OR REPLACE FUNCTION h3index_spgist_config(internal, internal) RETURNS void
+    AS 'h3' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
+--@ internal
+CREATE OR REPLACE FUNCTION h3index_spgist_choose(internal, internal) RETURNS void
+    AS 'h3' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
+--@ internal
+CREATE OR REPLACE FUNCTION h3index_spgist_picksplit(internal, internal) RETURNS void
+    AS 'h3' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
+--@ internal
+CREATE OR REPLACE FUNCTION h3index_spgist_inner_consistent(internal, internal) RETURNS void
+    AS 'h3' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
+--@ internal
+CREATE OR REPLACE FUNCTION h3index_spgist_leaf_consistent(internal, internal) RETURNS boolean
+    AS 'h3' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
+
+-- intentionally *not* marked as DEFAULT,
+-- until we are satisfied with the implementation
+CREATE OPERATOR CLASS h3index_ops_experimental
+FOR TYPE h3index USING spgist
+AS
+ -- OPERATOR   1  <<  ,  -- RTLeftStrategyNumber
+ -- OPERATOR   2  &<  ,  -- RTOverLeftStrategyNumber
+ -- OPERATOR   3  &&  ,  -- RTOverlapStrategyNumber
+ -- OPERATOR   4  &>  ,  -- RTOverRightStrategyNumber
+ -- OPERATOR   5  >>  ,  -- RTRightStrategyNumber
+    OPERATOR   6   =  ,  -- RTSameStrategyNumber
+    OPERATOR   7  @>  ,  -- RTContainsStrategyNumber
+    OPERATOR   8  <@  ,  -- RTContainedByStrategyNumber
+ -- OPERATOR   9  &<| ,  -- RTOverBelowStrategyNumber
+ -- OPERATOR  10  <<| ,  -- RTBelowStrategyNumber
+ -- OPERATOR  11  |>> ,  -- RTAboveStrategyNumber
+ -- OPERATOR  12  |&> ,  -- RTOverAboveStrategyNumber
+    FUNCTION  1  h3index_spgist_config(internal, internal),
+    FUNCTION  2  h3index_spgist_choose(internal, internal),
+    FUNCTION  3  h3index_spgist_picksplit(internal, internal),
+    FUNCTION  4  h3index_spgist_inner_consistent(internal, internal),
+    FUNCTION  5  h3index_spgist_leaf_consistent(internal, internal);

h3/sql/updates/h3--4.1.4--unreleased.sql

@@ -25,3 +25,27 @@ AS 'h3' LANGUAGE C IMMUTABLE
 CALLED ON NULL INPUT PARALLEL SAFE; COMMENT ON FUNCTION
     h3_polygon_to_cells_experimental(polygon, polygon[], integer, text)
 IS 'Takes an exterior polygon [and a set of hole polygon] and returns the set of hexagons that best fit the structure.';
+
+-- SP-GiST operator class
+CREATE OR REPLACE FUNCTION h3index_spgist_config(internal, internal) RETURNS void
+    AS 'h3' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
+CREATE OR REPLACE FUNCTION h3index_spgist_choose(internal, internal) RETURNS void
+    AS 'h3' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
+CREATE OR REPLACE FUNCTION h3index_spgist_picksplit(internal, internal) RETURNS void
+    AS 'h3' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
+CREATE OR REPLACE FUNCTION h3index_spgist_inner_consistent(internal, internal) RETURNS void
+    AS 'h3' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
+CREATE OR REPLACE FUNCTION h3index_spgist_leaf_consistent(internal, internal) RETURNS boolean
+    AS 'h3' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
+
+-- intentionally *not* marked as DEFAULT
+CREATE OPERATOR CLASS h3index_ops_experimental FOR TYPE h3index USING spgist AS
+    OPERATOR  6   =   ,
+    OPERATOR  7   @>  ,
+    OPERATOR  8  <@   ,
+
+    FUNCTION  1  h3index_spgist_config(internal, internal),
+    FUNCTION  2  h3index_spgist_choose(internal, internal),
+    FUNCTION  3  h3index_spgist_picksplit(internal, internal),
+    FUNCTION  4  h3index_spgist_inner_consistent(internal, internal),
+    FUNCTION  5  h3index_spgist_leaf_consistent(internal, internal);