# GeoPackage vector

This driver implements support for access to spatial tables in the OGC GeoPackage format standard. The GeoPackage standard uses a SQLite database file as a generic container, and the standard defines:

- Expected metadata tables (`gpkg_contents`, `gpkg_spatial_ref_sys`, `gpkg_geometry_columns`)
- Binary format encoding for geometries in spatial tables (basically a GPKG standard header object followed by ISO standard well-known binary (WKB))
- Naming and conventions for extensions (extended feature types) and indexes (how to use SQLite r-tree in an interoperable manner)

This driver reads and writes SQLite files from the file system, so it must be run by a user with read/write access to the files it is working with.

Starting with GDAL 2.0, the driver also supports reading and writing the following non-linear geometry types :CIRCULARSTRING, COMPOUNDCURVE, CURVEPOLYGON, MULTICURVE and MULTISURFACE

Starting with GDAL 2.0, GeoPackage raster/tiles are supported. See GeoPackage raster documentation page

## Limitations

- GeoPackage only supports one geometry column per table.
- Before GDAL 2.0, the driver did not implement the GeoPackage spatial index extension.
- The core GeoPackage specification does not currently support non-spatial tables, but starting with GDAL 2.0, the driver allows creating and reading such tables via the Aspatial Support (`gdal_aspatial`) extension.

## SQL

The driver supports OGR attribute filters, and users are expected to provide filters in the SQLite dialect, as they will be executed directly against the database.

Starting with GDAL 2.0, SQL SELECT statements passed to ExecuteSQL() are also executed directly against the database. If Spatialite is used, a recent version (4.2.0) is needed and use of explicit cast operators AsGPB() is required to transform GeoPackage geometries to Spatialite geometries (the reverse conversion from Spatialite geometries is automatically done by the GPKG driver). It is also possible to use with any Spatialite version, but in a slower way, by specifying the "INDIRECT_SQLITE" dialect. In which case, GeoPackage geometries automatically appear as Spatialite geometries after translation by OGR.

### SQL functions

Starting with GDAL 2.0, the following SQL functions, from the GeoPackage specification, are available :

- ST_MinX(geom Geometry) : returns the minimum X coordinate of the geometry
- ST_MinY(geom Geometry) : returns the minimum Y coordinate of the geometry
- ST_MaxX(geom Geometry) : returns the maximum X coordinate of the geometry
- ST_MaxY(geom Geometry) : returns the maximum Y coordinate of the geometry
- ST_IsEmpty(geom Geometry) : returns 1 is the geometry is empty (but not null), e.g. a POINT EMPTY geometry
- ST_GeometryType(geom Geometry) : returns the geometry type : 'POINT', 'LINESTRING', 'POLYGON', 'MULTIPOLYGON', 'MULITLINESTRING', 'MULTIPOINT', 'GEOMETRYCOLLECTION'
- ST_SRID(geom Geometry) : returns the SRID of the geometry
- GPKG_IsAssignable(expected_geom_type String, actual_geom_type String) : mainly, needed for the 'Geometry Type Triggers Extension'

The following functions, with identical syntax and semantics as in Spatialite, are also available :

- CreateSpatialIndex(table_name String, geom_column_name String) : creates a spatial index (RTree) on the specified table/geometry column
- DisableSpatialIndex(table_name String, geom_column_name String) : disable an existing spatial index (RTree) on the specified table/geometry column

### Link with Spatialite

Starting with GDAL 2.0, if it has been compiled against Spatialite 4.2 or later, it is also possible to use Spatialite SQL functions. Explicit transformation from GPKG geometry binary encoding to Spatialite geometry binary encoding must be done.

    ogrinfo poly.gpkg -sql "SELECT ST_Buffer(CastAutomagic(geom),5) FROM poly"

Starting with Spatialite 4.3, CastAutomagic is no longer needed.

## Transaction support (GDAL >= 2.0)

The driver implements transactions at the database level, per RFC 54

## Creation Issues

When creating a new GeoPackage file, the driver will attempt to force the database into a UTF-8 mode for text handling, satisfying the OGR strict UTF-8 capability. For pre-existing files, the driver will work with whatever it's given.

### Dataset Creation Options

None related to vector

### Layer Creation Options

- GEOMETRY_NAME: Column to use for the geometry column. Default to "geom". Note: option was called GEOMETRY_COLUMN in releases before GDAL 2
- GEOMETRY_NULLABLE: (GDAL >=2.0) Whether the values of the geometry column can be NULL. Can be set to NO so that geometry is required. Default to "YES"
- FID: Column name to use for the OGR FID (primary key in the SQLite database). Default to "fid"
- OVERWRITE: If set to "YES" will delete any existing layers that have the same name as the layer being created. Default to NO
- SPATIAL_INDEX: (GDAL >=2.0) If set to "YES" will create a spatial index for this layer. Default to YES
- PRECISION: (GDAL >=2.0) This may be "YES" to force new fields created on this layer to try and represent the width of text fields (in terms of UTF-8 characters, not bytes), if available using TEXT(width) types. If "NO" then the type TEXT will be used instead. The default is "YES".

- TRUNCATE_FIELDS: (GDAL >=2.0) This may be "YES" to force truncated of field values that exceed the maximum allowed width of text fields, and also to "fix" the passed string if needed to make it a valid UTF-8 string. If "NO" then the value is not truncated nor modified. The default is "NO".

- IDENTIFIER=string: (GDAL >=2.0) Identifier of the layer, as put in the contents table.

- DESCRIPTION=string: (GDAL >=2.0) Description of the layer, as put in the contents table.

### Metadata

(GDAL >=2.0) GDAL uses the standardized `gpkg_metadata` and `gpkg_metadata_reference` tables to read and write metadata, on the dataset and layer objects.

GDAL metadata, from the default metadata domain and possibly other metadata domains, is serialized in a single XML document, conformant with the format used in GDAL PAM (Persistent Auxiliary Metadata) .aux.xml files, and registered with md_scope=dataset and md_standard_uri=http://gdal.org in gpkg_metadata. For the dataset, this entry is referenced in gpkg_metadata_reference with a reference_scope=geopackage. For a layer, this entry is referenced in gpkg_metadata_reference with a reference_scope=table and table_name={name of the table}

Metadata not originating from GDAL can be read by the driver and will be exposed as metadata items with keys of the form GPKG_METADATA_ITEM_XXX and values the content of the metadata columns of the gpkg_metadata table. Update of such metadata is not currently supported through GDAL interfaces ( although it can be through direct SQL commands).

The specific DESCRIPTION and IDENTIFIER metadata item of the default metadata domain can be used in read/write to read from/update the corresponding columns of the gpkg_contents table.

### Examples

- Simple translation of a single shapefile into GeoPackage. The table 'abc' will be created with the features from abc.shp and attributes from abc.dbf. The file `filename.gpkg` must not already exist, as it will be created.

      % ogr2ogr -f GPKG filename.gpkg abc.shp

- Translation of a directory of shapefiles into a GeoSpackage. Each file will end up as a new table within the GPKG file. The file `filename.gpkg` must not already exist, as it will be created.

      % ogr2ogr -f GPKG filename.gpkg ./path/to/dir

- Translation of a PostGIS database into a GeoPackage. Each table in the database will end up as a table in the GPKG file. The file `filename.gpkg` must not already exist, as it will be created.

      % ogr2ogr -f GPKG filename.gpkg PG:'dbname=mydatabase host=localhost'

### See Also

- SQLite

- GeoPackage raster documentation page