{"id":13423419,"url":"https://github.com/dlr-eoc/pgh3","last_synced_at":"2025-03-15T17:31:42.460Z","repository":{"id":44636383,"uuid":"148502422","full_name":"dlr-eoc/pgh3","owner":"dlr-eoc","description":"PostgreSQL extension for the H3 hierarchical geospatial indexing system","archived":true,"fork":false,"pushed_at":"2022-02-03T05:58:50.000Z","size":146,"stargazers_count":85,"open_issues_count":1,"forks_count":14,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-10-26T23:10:40.430Z","etag":null,"topics":["geospatial","h3","hexagon","postgis","postgresql","spatial-indexing","ukis"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dlr-eoc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-09-12T15:32:27.000Z","updated_at":"2024-05-19T03:06:02.000Z","dependencies_parsed_at":"2022-07-21T01:32:50.425Z","dependency_job_id":null,"html_url":"https://github.com/dlr-eoc/pgh3","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dlr-eoc%2Fpgh3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dlr-eoc%2Fpgh3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dlr-eoc%2Fpgh3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dlr-eoc%2Fpgh3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dlr-eoc","download_url":"https://codeload.github.com/dlr-eoc/pgh3/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243766830,"owners_count":20344820,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["geospatial","h3","hexagon","postgis","postgresql","spatial-indexing","ukis"],"created_at":"2024-07-31T00:00:34.148Z","updated_at":"2025-03-15T17:31:42.127Z","avatar_url":"https://github.com/dlr-eoc.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"# [PostgreSQL](https://www.postgresql.org) extension for the [H3](https://uber.github.io/h3) hierarchical geospatial indexing system\n\n![](doc/hexagons-example.png)\n\nThis extension integrates with the [PostGIS](https://postgis.net/) geometry type. Namely `Point`, `Polygon` and `MultiPolygon` geometries are supported.\n\nTo see the functions implemented in this extension please refer to the [SQL API](doc/pgh3.md).\n\n\n## Installation\n\n__Compile H3 as a shared library__. The source is available on [github](https://github.com/uber/h3), there are als\no detailed instructions for building H3 available in that repository, but to make H3 work with this extension there \nare additional build flags required. There are essentialy two ways to compile H3 which allow building the pgh3 extension\nlater.\n\nCompile H3 as a static library. This allows statically linking H3 to the pgh3 extension. \n\n    cmake -DCMAKE_C_FLAGS=-fPIC .\n    make\n    sudo make install\n\nOr compile H3 as a shared library. This creates a dynamically loaded library which may also be used by other programs. When\nyou update the H3 library, all programms using it will automatically use the new version (PostgreSQL needs to \nbe restarted for that).\n\n    cmake -DBUILD_SHARED_LIBS=1 -DCMAKE_INSTALL_PREFIX:PATH=/usr .\n    make\n    sudo make install\n\nIn case you have set up your `LD_LIBRARY_PATH` for PostgreSQL to also look in `/usr/local` for libraries, you can ommit the `-DCMAKE_INSTALL_PREFIX:PATH=/usr` switch.\n\n__Compile the pgh3 extension__:\n\n    make\n    sudo make install\n\n__Run the tests__ (this is an optional step):\n\n    make installcheck\n\n## Usage\n\nBefore using this extension, it needs to be added to the databases using postgresqls [CREATE EXTENSION](https://www.postgresql.org/docs/current/static/sql-createextension.html) command:\n\n    create extension postgis; -- dependency of pgh3, must be created first\n    create extension pgh3;\n\nFor usage examples see the unittests in the `sql/*_test.sql` files.\n\n### Configuration\n\nThis extensions allows configuring some parts of its behaviour. This configuration is done using additional keys to `postgresql.conf`\n\n#### pgh3.polyfill_mem\n\nThe H3 `polyfill` function requires a preallocation of the memory for the generates indexes. Depending of the size of the\ngiven polygon, its shape and the resolution this may exhaust the memory given to this extension. In this case\nthis function will be terminated by the database server and a corresponding notice will be given.\n\nThis memory limit can be increased using the `pgh3.polyfill_mem` configuration parameter in the `postgresql.conf` file. The \ndefault value for this setting 1024MB (PostgreSQL internal `MaxAllocSize`). Syntax for the setting is\n\n    pgh3.polyfill_mem = 1024MB\n\nFor values larger than `MaxAllocSize`, the PostgreSQL `MemoryContextAllocHuge` allocator will be used.\n\n_This setting is only available when using a PostgreSQL version \u003e= 10_. On earlier versions the memory limit is set to 1024MB.\n\n### Error handling\n\nMost errors emmitted by this extension are making use of the [PostgreSQL error codes](https://www.postgresql.org/docs/current/errcodes-appendix.html).\nThis allows a more explicit handling of certain errors in application code or PL/pgSQL procedures. To give a short example using the `psql` command line:\n\n    h3=# \\set VERBOSITY verbose \n    h3=# select count(*) from h3_polyfill(st_geomfromtext('POLYGON((30 10,40 40,20 40,10 20,30 10))'), 10);\n    ERROR:  53400: pgh3.polyfill_mem: requested memory allocation (7.58GB) exceeded the configured value (1023MB).\n    CONTEXT:  PL/pgSQL function h3_polyfill(geometry,integer) line 4 at RETURN QUERY\n    LOCATION:  __h3_polyfill_palloc0, util.c:158\n\nLooking at he PostgreSQL documentaion, error code `53400` stands for `configuration_limit_exceeded`.\n\n\n## TODO\n\n* Implement more parts of the H3 API\n* Use the `numeric`-type for H3 indexes?\n\n# Legal an Licensing\n\nThis software is licensed under the [Apache 2.0 License](LICENSE.txt).\n\n(c) 2018 German Aerospace Center (DLR); German Remote Sensing Data Center; Department: Geo-Risks and Civil Security\n\n[![UKIS](doc/ukis-logo.png)](https://www.dlr.de/eoc/en/desktopdefault.aspx/tabid-5413/10560_read-21914/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdlr-eoc%2Fpgh3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdlr-eoc%2Fpgh3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdlr-eoc%2Fpgh3/lists"}