GeoPackage Feature ID Strategy

In order to facilitate importing and exporting between GeoGig and GeoPackage, there must be a system that keeps track of feature id mappings between the two formats. GeoGig uses strings to represent feature IDs, while GeoPackage uses numbers. We cannot simply use the ID provided by GeoPackage due to the fact that they are auto-incrementing integers. If more than one user adds features to different GeoPackages, they could be assigned the same ID which would result in conflicts when they both imported the GeoPackage. We also cannot count on IDs in GeoGig being parseable as integers because the features can come from other sources where the ID is provided as a string. Rather than adding a new attribute to the feature type to store the GeoGig feature ID, we can make a table inside the GeoPackage that keeps track of these mappings.

On Export

When a GeoPackage export is performed, GeoGig will transform each exported feature to convert its ID into a numeric value. It will also keep track of which numeric ID maps to each GeoGig feature path. It will then create a _fids mapping table in the GeoPackage to store all of these mappings.

On Import

During import, GeoGig will check the GeoPackage for the existence of the _fids table. If it exists, it will transform all incoming features with a fid mapping to convert its feature ID to the original GeoGig feature ID. Features that do not have a mapping are new and will be assigned a newly generated feature ID. If there is no mapping table, all features will be treated as new and be assigned newly generated feature IDs.

This mapping will be done for both the regular import/export, as well as the import/export with the interchange format enabled.

Web Synchronization

In order to prevent an excessive amount of data from being transferred while using GeoPackages, the following steps should be taken:

1. Export a GeoPackage with the interchange format enabled.
2. Make edits to the GeoPackage with another tool. All edits will be logged in the audit tables set up by the interchange format.
3. Import the GeoPackage with the interchange format enabled. This will cause the import to be based on the commit where the export happened, then merged into the current branch, or the one specified by the root parameter.
4. Import will return the feature ID mappings for newly added features as well as the import commit and merge commit so that the client can update the GeoPackage to the state at the import commit.
5. If the client wants to update the GeoPackage to the latest state, they can perform an export-diff?format=geopkg operation to get all of the changes between the import commit and the merge commit in a smaller GeoPackage file which can be merged with their local GeoPackage.
   • All features that were modified will be exported with the GeoPackage.
   • All changes will be in a table called _changes of the exported GeoPackage.
   • Feature ID mappings may not match up with the client's GeoPackage, so the client will need to match up changes by the GeoGig feature ID.
   • Once the local GeoPackage has been updated, the audit table should be updated with the merge commit ID and the audit log should be cleared.

Note: In the case of a conflict when merging new features to the target branch, the new feature ID mappings will still be returned. Conflicts can then be resolved by the client and committed. Then the GeoPackage can be updated to the new commit.